actioncable 5.0.0.beta3 → 5.0.0.beta4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e3e7b9ae96c4f9f359281abaa75f8b909a8fb04f
-  data.tar.gz: 41a9536aea144e25988a510069c3b07b0250aa5b
+  metadata.gz: a5d4383eac68ebad915b6ba22ef556a6dbcdabf5
+  data.tar.gz: 04c95deb8c0ae1e283b0fd630172646f86d4e541
 SHA512:
-  metadata.gz: 6f1879623b43518932a8c295c72acc97b7dd97008d1925dc3130f0398fbaa68a22d4bb0f6ad9f86b9d85e36c8a88e0070c235e4ac79480079d1cec546651e87e
-  data.tar.gz: a7c49b2304c60bb4d50674a457164a14b9d5f4ae0dc4aaabf65569bdf2a7f493ad6e5938162b017e9f0ff80cf2cd8fa028590b00a32ccbe14837d4ebf5d638c0
+  metadata.gz: 9b37dfd802d1c0f95b97e5afe0832a0cf9143b77cc17615ed6a402dead98856e4c759a503c301a1a5359a95116fcbfe812dfb18655b6476b6548b7b182d988f4
+  data.tar.gz: 2657c42b971d5dc208906c98a3545aae2111c6775e6478561bb91071f854e83bd6c8b9eb7a8080d0c5d17bd67ae95e2385ac5b97d5ef063d917825bb0898c4a6

data/CHANGELOG.md

@@ -1,11 +1,57 @@
+## Rails 5.0.0.beta4 (April 27, 2016) ##
+
+*   WebSocket protocol negotiation.
+
+    Introduces an Action Cable protocol version that moves independently
+    of and, hopefully, more slowly than Action Cable itself. Client sockets
+    negotiate a protocol with the Cable server using WebSockets' native
+    subprotocol support:
+      * https://tools.ietf.org/html/rfc6455#section-1.9
+      * https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_servers#Subprotocols
+
+    If they can't negotiate a compatible protocol (usually due to upgrading
+    the Cable server with a browser still running old JavaScript) then the
+    client knows to disconnect, cease retrying, and tell the app that it hit
+    a protocol mismatch.
+
+    This allows us to evolve the Action Cable message format, handshaking,
+    pings, acknowledgements, and more without breaking older clients'
+    expectations of server behavior.
+
+    *Daniel Rhodes*
+
+*   Pubsub: automatic stream decoding.
+
+        stream_for @room, coder: ActiveSupport::JSON do |message|
+          # `message` is a Ruby hash here instead of a JSON string
+
+    The `coder` must respond to `#decode`. Defaults to `coder: nil`
+    which skips decoding entirely.
+
+    *Jeremy Daer*
+
+*   Add ActiveSupport::Notifications to ActionCable::Channel.
+
+    *Matthew Wear*
+
+*   Safely support autoloading and class unloading, by preventing concurrent
+    loads, and disconnecting all cables during reload.
+
+    *Matthew Draper*
+
+*   Ensure ActionCable behaves correctly for non-string queue names.
+
+    *Jay Hayes*
+
 ## Rails 5.0.0.beta3 (February 24, 2016) ##
 
-*  Added ActionCable::SubscriptionAdapter::EventedRedis.em_redis_connector/redis_connector and
-   ActionCable::SubscriptionAdapter::Redis.redis_connector factory methods for redis connections, 
-   so you can overwrite with your own initializers. This is used when you want to use different-than-standard Redis adapters,
-   like for Makara distributed Redis.
+*   Added `em_redis_connector` and `redis_connector` to
+   `ActionCable::SubscriptionAdapter::EventedRedis` and added `redis_connector`
+    to `ActionCable::SubscriptionAdapter::Redis`, so you can overwrite with your
+    own initializers. This is used when you want to use different-than-standard
+    Redis adapters, like for Makara distributed Redis.
 
-   *DHH*
+    *DHH*
 
 ## Rails 5.0.0.beta2 (February 01, 2016) ##
 
@@ -28,7 +74,7 @@
     ActionCable was changed from`config/redis/cable.yml` to
     `config/cable.yml`.
 
-   *Jon Moss*
+    *Jon Moss*
 
 ## Rails 5.0.0.beta1 (December 18, 2015) ##
 

data/README.md

@@ -178,7 +178,7 @@ App.cable.subscriptions.create "AppearanceChannel",
 ```
 
 Simply calling `App.cable.subscriptions.create` will setup the subscription, which will call `AppearanceChannel#subscribed`,
-which in turn is linked to original `App.cable` -> `ApplicationCable::Connection` instances.
+which in turn is linked to the original `App.cable` -> `ApplicationCable::Connection` instances.
 
 Next, we link the client-side `appear` method to `AppearanceChannel#appear(data)`. This is possible because the server-side
 channel instance will automatically expose the public methods declared on the class (minus the callbacks), so that these
@@ -339,21 +339,21 @@ Rails.application.config.action_cable.disable_request_forgery_protection = true
 
 ### Consumer Configuration
 
-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.
+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.
 There are two ways you can do this.
 
 The first is to simply pass it in when creating your consumer. For a standalone server,
 this would be something like: `App.cable = ActionCable.createConsumer("ws://example.com:28080")`, and for an in-app server,
 something like: `App.cable = ActionCable.createConsumer("/cable")`.
 
-The second option is to pass the server url through the `action_cable_meta_tag` in your layout.
-This uses a url or path typically set via `config.action_cable.url` in the environment configuration files, or defaults to "/cable".
+The second option is to pass the server URL through the `action_cable_meta_tag` in your layout.
+This uses a URL or path typically set via `config.action_cable.url` in the environment configuration files, or defaults to "/cable".
 
-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
+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
 for your Action Cable server, but development might remain http and use the ws scheme. You might use localhost in development and your
 domain in production.
 
-In any case, to vary the WebSocket url between environments, add the following configuration to each environment:
+In any case, to vary the WebSocket URL between environments, add the following configuration to each environment:
 
 ```ruby
 config.action_cable.url = "ws://example.com:28080"
@@ -412,12 +412,12 @@ The above will start a cable server on port 28080.
 
 ### In app
 
-If you are using a threaded server like Puma or Thin, the current implementation of Action Cable can run side-along with your Rails application. For example, to listen for WebSocket requests on `/cable`, mount the server at that path:
+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`:
 
 ```ruby
-# config/routes.rb
-Example::Application.routes.draw do
-  mount ActionCable.server => '/cable'
+# config/application.rb
+class Application < Rails::Application
+  config.action_cable.mount_path = '/websocket'
 end
 ```
 
@@ -445,12 +445,8 @@ connection management is handled internally by utilizing Ruby’s native thread
 support, which means you can use all your regular Rails models with no problems
 as long as you haven’t committed any thread-safety sins.
 
-But this also means that Action Cable needs to run in its own server process.
-So you'll have one set of server processes for your normal web work, and another
-set of server processes for the Action Cable.
-
 The Action Cable server does _not_ need to be a multi-threaded application server.
-This is because Action Cable uses the [Rack socket hijacking API](http://old.blog.phusion.nl/2013/01/23/the-new-rack-socket-hijacking-api/)
+This is because Action Cable uses the [Rack socket hijacking API](http://www.rubydoc.info/github/rack/rack/file/SPEC#Hijacking)
 to take over control of connections from the application server. Action Cable
 then manages connections internally, in a multithreaded manner, regardless of
 whether the application server is multi-threaded or not. So Action Cable works

data/lib/action_cable.rb

@@ -29,13 +29,14 @@ module ActionCable
   extend ActiveSupport::Autoload
 
   INTERNAL = {
-    identifiers: {
-      ping: '_ping'.freeze
-    },
     message_types: {
+      welcome: 'welcome'.freeze,
+      ping: 'ping'.freeze,
       confirmation: 'confirm_subscription'.freeze,
       rejection: 'reject_subscription'.freeze
-    }
+    },
+    default_mount_path: '/cable'.freeze,
+    protocols: ["actioncable-v1-json".freeze, "actioncable-unsupported".freeze].freeze
   }
 
   # Singleton instance of the server

data/lib/action_cable/channel/base.rb

@@ -160,13 +160,16 @@ module ActionCable
         action = extract_action(data)
 
         if processable_action?(action)
-          dispatch_action(action, data)
+          payload = { channel_class: self.class.name, action: action, data: data }
+          ActiveSupport::Notifications.instrument("perform_action.action_cable", payload) do
+            dispatch_action(action, data)
+          end
         else
           logger.error "Unable to process #{action_signature(action, data)}"
         end
       end
 
-      # Called by the cable connection when its cut, so the channel has a chance to cleanup with callbacks.
+      # Called by the cable connection when it's cut, so the channel has a chance to cleanup with callbacks.
       # This method is not intended to be called directly by the user. Instead, overwrite the #unsubscribed callback.
       def unsubscribe_from_channel # :nodoc:
         run_callbacks :unsubscribe do
@@ -192,7 +195,11 @@ module ActionCable
         # the proper channel identifier marked as the recipient.
         def transmit(data, via: nil)
           logger.info "#{self.class.name} transmitting #{data.inspect.truncate(300)}".tap { |m| m << " (via #{via})" if via }
-          connection.transmit ActiveSupport::JSON.encode(identifier: @identifier, message: data)
+
+          payload = { channel_class: self.class.name, data: data, via: via }
+          ActiveSupport::Notifications.instrument("transmit.action_cable", payload) do
+            connection.transmit identifier: @identifier, message: data
+          end
         end
 
         def defer_subscription_confirmation!
@@ -265,8 +272,11 @@ module ActionCable
         def transmit_subscription_confirmation
           unless subscription_confirmation_sent?
             logger.info "#{self.class.name} is transmitting the subscription confirmation"
-            connection.transmit ActiveSupport::JSON.encode(identifier: @identifier, type: ActionCable::INTERNAL[:message_types][:confirmation])
-            @subscription_confirmation_sent = true
+
+            ActiveSupport::Notifications.instrument("transmit_subscription_confirmation.action_cable", channel_class: self.class.name) do
+              connection.transmit identifier: @identifier, type: ActionCable::INTERNAL[:message_types][:confirmation]
+              @subscription_confirmation_sent = true
+            end
           end
         end
 
@@ -277,7 +287,10 @@ module ActionCable
 
         def transmit_subscription_rejection
           logger.info "#{self.class.name} is transmitting the subscription rejection"
-          connection.transmit ActiveSupport::JSON.encode(identifier: @identifier, type: ActionCable::INTERNAL[:message_types][:rejection])
+
+          ActiveSupport::Notifications.instrument("transmit_subscription_rejection.action_cable", channel_class: self.class.name) do
+            connection.transmit identifier: @identifier, type: ActionCable::INTERNAL[:message_types][:rejection]
+          end
         end
     end
   end

data/lib/action_cable/channel/periodic_timers.rb

@@ -12,11 +12,42 @@ module ActionCable
       end
 
       module ClassMethods
-        # Allows you to call a private method <tt>every</tt> so often seconds. This periodic timer can be useful
-        # for sending a steady flow of updates to a client based off an object that was configured on subscription.
-        # It's an alternative to using streams if the channel is able to do the work internally.
-        def periodically(callback, every:)
-          self.periodic_timers += [ [ callback, every: every ] ]
+        # Periodically performs a task on the channel, like updating an online
+        # user counter, polling a backend for new status messages, sending
+        # regular "heartbeat" messages, or doing some internal work and giving
+        # progress updates.
+        #
+        # Pass a method name or lambda argument or provide a block to call.
+        # Specify the calling period in seconds using the <tt>every:</tt>
+        # keyword argument.
+        #
+        #     periodically :transmit_progress, every: 5.seconds
+        #
+        #     periodically every: 3.minutes do
+        #       transmit action: :update_count, count: current_count
+        #     end
+        #
+        def periodically(callback_or_method_name = nil, every:, &block)
+          callback =
+            if block_given?
+              raise ArgumentError, 'Pass a block or provide a callback arg, not both' if callback_or_method_name
+              block
+            else
+              case callback_or_method_name
+              when Proc
+                callback_or_method_name
+              when Symbol
+                -> { __send__ callback_or_method_name }
+              else
+                raise ArgumentError, "Expected a Symbol method name or a Proc, got #{callback_or_method_name.inspect}"
+              end
+            end
+
+          unless every.kind_of?(Numeric) && every > 0
+            raise ArgumentError, "Expected every: to be a positive number of seconds, got #{every.inspect}"
+          end
+
+          self.periodic_timers += [[ callback, every: every ]]
         end
       end
 
@@ -27,14 +58,21 @@ module ActionCable
 
         def start_periodic_timers
           self.class.periodic_timers.each do |callback, options|
-            active_periodic_timers << Concurrent::TimerTask.new(execution_interval: options[:every]) do
-              connection.worker_pool.async_run_periodic_timer(self, callback)
+            active_periodic_timers << start_periodic_timer(callback, every: options.fetch(:every))
+          end
+        end
+
+        def start_periodic_timer(callback, every:)
+          connection.server.event_loop.timer every do
+            connection.worker_pool.async_invoke connection do
+              instance_exec(&callback)
             end
           end
         end
 
         def stop_periodic_timers
           active_periodic_timers.each { |timer| timer.shutdown }
+          active_periodic_timers.clear
         end
     end
   end

data/lib/action_cable/channel/streams.rb

@@ -1,8 +1,8 @@
 module ActionCable
   module Channel
-    # Streams allow channels to route broadcastings to the subscriber. A broadcasting is, as discussed elsewhere, a pub/sub queue where any data
+    # Streams allow channels to route broadcastings to the subscriber. A broadcasting is, as discussed elsewhere, a pubsub queue where any data
     # placed into it is automatically sent to the clients that are connected at that time. It's purely an online queue, though. If you're not
-    # streaming a broadcasting at the very moment it sends out an update, you will not get that update, if you connect after it has been sent.
+    # streaming a broadcasting at the very moment it sends out an update, you will not get that update, even if you connect after it has been sent.
     #
     # Most commonly, the streamed broadcast is sent straight to the subscriber on the client-side. The channel just acts as a connector between
     # the two parties (the broadcaster and the channel subscriber). Here's an example of a channel that allows subscribers to get all new
@@ -46,9 +46,7 @@ module ActionCable
     #     def subscribed
     #       @room = Chat::Room[params[:room_number]]
     #
-    #       stream_for @room, -> (encoded_message) do
-    #         message = ActiveSupport::JSON.decode(encoded_message)
-    #
+    #       stream_for @room, coder: ActiveSupport::JSON do |message|
     #         if message['originated_at'].present?
     #           elapsed_time = (Time.now.to_f - message['originated_at']).round(2)
     #
@@ -71,15 +69,21 @@ module ActionCable
 
       # Start streaming from the named <tt>broadcasting</tt> pubsub queue. Optionally, you can pass a <tt>callback</tt> that'll be used
       # instead of the default of just transmitting the updates straight to the subscriber.
-      def stream_from(broadcasting, callback = nil)
+      # Pass `coder: ActiveSupport::JSON` to decode messages as JSON before passing to the callback.
+      # Defaults to `coder: nil` which does no decoding, passes raw messages.
+      def stream_from(broadcasting, callback = nil, coder: nil, &block)
+        broadcasting = String(broadcasting)
+
         # Don't send the confirmation until pubsub#subscribe is successful
         defer_subscription_confirmation!
 
-        callback ||= default_stream_callback(broadcasting)
-        streams << [ broadcasting, callback ]
+        # Build a stream handler by wrapping the user-provided callback with
+        # a decoder or defaulting to a JSON-decoding retransmitter.
+        handler = worker_pool_stream_handler(broadcasting, callback || block, coder: coder)
+        streams << [ broadcasting, handler ]
 
-        Concurrent.global_io_executor.post do
-          pubsub.subscribe(broadcasting, callback, lambda do
+        connection.server.event_loop.post do
+          pubsub.subscribe(broadcasting, handler, lambda do
             transmit_subscription_confirmation
             logger.info "#{self.class.name} is streaming from #{broadcasting}"
           end)
@@ -89,8 +93,11 @@ module ActionCable
       # Start streaming the pubsub queue for the <tt>model</tt> in this channel. Optionally, you can pass a
       # <tt>callback</tt> that'll be used instead of the default of just transmitting the updates straight
       # to the subscriber.
-      def stream_for(model, callback = nil)
-        stream_from(broadcasting_for([ channel_name, model ]), callback)
+      #
+      # Pass `coder: ActiveSupport::JSON` to decode messages as JSON before passing to the callback.
+      # Defaults to `coder: nil` which does no decoding, passes raw messages.
+      def stream_for(model, callback = nil, coder: nil, &block)
+        stream_from(broadcasting_for([ channel_name, model ]), callback || block, coder: coder)
       end
 
       # Unsubscribes all streams associated with this channel from the pubsub queue.
@@ -108,11 +115,60 @@ module ActionCable
           @_streams ||= []
         end
 
-        def default_stream_callback(broadcasting)
+        # Always wrap the outermost handler to invoke the user handler on the
+        # worker pool rather than blocking the event loop.
+        def worker_pool_stream_handler(broadcasting, user_handler, coder: nil)
+          handler = stream_handler(broadcasting, user_handler, coder: coder)
+
+          -> message do
+            connection.worker_pool.async_invoke handler, :call, message, connection: connection
+          end
+        end
+
+        # May be overridden to add instrumentation, logging, specialized error
+        # handling, or other forms of handler decoration.
+        #
+        # TODO: Tests demonstrating this.
+        def stream_handler(broadcasting, user_handler, coder: nil)
+          if user_handler
+            stream_decoder user_handler, coder: coder
+          else
+            default_stream_handler broadcasting, coder: coder
+          end
+        end
+
+        # May be overridden to change the default stream handling behavior
+        # which decodes JSON and transmits to client.
+        #
+        # TODO: Tests demonstrating this.
+        #
+        # TODO: Room for optimization. Update transmit API to be coder-aware
+        # so we can no-op when pubsub and connection are both JSON-encoded.
+        # Then we can skip decode+encode if we're just proxying messages.
+        def default_stream_handler(broadcasting, coder:)
+          coder ||= ActiveSupport::JSON
+          stream_transmitter stream_decoder(coder: coder), broadcasting: broadcasting
+        end
+
+        def stream_decoder(handler = identity_handler, coder:)
+          if coder
+            -> message { handler.(coder.decode(message)) }
+          else
+            handler
+          end
+        end
+
+        def stream_transmitter(handler = identity_handler, broadcasting:)
+          via = "streamed from #{broadcasting}"
+
           -> (message) do
-            transmit ActiveSupport::JSON.decode(message), via: "streamed from #{broadcasting}"
+            transmit handler.(message), via: via
           end
         end
+
+        def identity_handler
+          -> message { message }
+        end
     end
   end
 end

data/lib/action_cable/connection.rb

@@ -8,6 +8,8 @@ module ActionCable
       autoload :ClientSocket
       autoload :Identification
       autoload :InternalChannel
+      autoload :FayeClientSocket
+      autoload :FayeEventLoop
       autoload :MessageBuffer
       autoload :Stream
       autoload :StreamEventLoop

data/lib/action_cable/connection/base.rb

@@ -40,7 +40,7 @@ module ActionCable
     # Second, we rely on the fact that the WebSocket connection is established with the cookies from the domain being sent along. This makes
     # it easy to use signed cookies that were set when logging in via a web interface to authorize the WebSocket connection.
     #
-    # Finally, we add a tag to the connection-specific logger with name of the current user to easily distinguish their messages in the log.
+    # Finally, we add a tag to the connection-specific logger with the name of the current user to easily distinguish their messages in the log.
     #
     # Pretty simple, eh?
     class Base
@@ -48,15 +48,16 @@ module ActionCable
       include InternalChannel
       include Authorization
 
-      attr_reader :server, :env, :subscriptions, :logger
-      delegate :stream_event_loop, :worker_pool, :pubsub, to: :server
+      attr_reader :server, :env, :subscriptions, :logger, :worker_pool, :protocol
+      delegate :event_loop, :pubsub, to: :server
 
-      def initialize(server, env)
-        @server, @env = server, env
+      def initialize(server, env, coder: ActiveSupport::JSON)
+        @server, @env, @coder = server, env, coder
 
+        @worker_pool = server.worker_pool
         @logger = new_tagged_logger
 
-        @websocket      = ActionCable::Connection::WebSocket.new(env, self, stream_event_loop)
+        @websocket      = ActionCable::Connection::WebSocket.new(env, self, event_loop, server.config.client_socket_class)
         @subscriptions  = ActionCable::Connection::Subscriptions.new(self)
         @message_buffer = ActionCable::Connection::MessageBuffer.new(self)
 
@@ -66,7 +67,7 @@ module ActionCable
 
       # Called by the server when a new WebSocket connection is established. This configures the callbacks intended for overwriting by the user.
       # This method should not be called directly -- instead rely upon on the #connect (and #disconnect) callbacks.
-      def process # :nodoc:
+      def process #:nodoc:
         logger.info started_request_message
 
         if websocket.possible? && allow_request_origin?
@@ -76,20 +77,22 @@ module ActionCable
         end
       end
 
-      # Data received over the WebSocket connection is handled by this method. It's expected that everything inbound is JSON encoded.
-      # The data is routed to the proper channel that the connection has subscribed to.
-      def receive(data_in_json)
+      # Decodes WebSocket messages and dispatches them to subscribed channels.
+      # WebSocket message transfer encoding is always JSON.
+      def receive(websocket_message) #:nodoc:
+        send_async :dispatch_websocket_message, websocket_message
+      end
+
+      def dispatch_websocket_message(websocket_message) #:nodoc:
         if websocket.alive?
-          subscriptions.execute_command ActiveSupport::JSON.decode(data_in_json)
+          subscriptions.execute_command decode(websocket_message)
         else
-          logger.error "Received data without a live WebSocket (#{data_in_json.inspect})"
+          logger.error "Ignoring message processed after the WebSocket was closed: #{websocket_message.inspect})"
         end
       end
 
-      # Send raw data straight back down the WebSocket. This is not intended to be called directly. Use the #transmit available on the
-      # Channel instead, as that'll automatically address the correct subscriber and wrap the message in JSON.
-      def transmit(data) # :nodoc:
-        websocket.transmit data
+      def transmit(cable_message) # :nodoc:
+        websocket.transmit encode(cable_message)
       end
 
       # Close the WebSocket connection.
@@ -114,7 +117,7 @@ module ActionCable
       end
 
       def beat
-        transmit ActiveSupport::JSON.encode(identifier: ActionCable::INTERNAL[:identifiers][:ping], message: Time.now.to_i)
+        transmit type: ActionCable::INTERNAL[:message_types][:ping], message: Time.now.to_i
       end
 
       def on_open # :nodoc:
@@ -151,10 +154,19 @@ module ActionCable
         attr_reader :message_buffer
 
       private
+        def encode(cable_message)
+          @coder.encode cable_message
+        end
+
+        def decode(websocket_message)
+          @coder.decode websocket_message
+        end
+
         def handle_open
+          @protocol = websocket.protocol
           connect if respond_to?(:connect)
           subscribe_to_internal_channel
-          confirm_connection_monitor_subscription
+          send_welcome_message
 
           message_buffer.process!
           server.add_connection(self)
@@ -173,11 +185,11 @@ module ActionCable
           disconnect if respond_to?(:disconnect)
         end
 
-        def confirm_connection_monitor_subscription
-          # Send confirmation message to the internal connection monitor channel.
+        def send_welcome_message
+          # Send welcome message to the internal connection monitor channel.
           # This ensures the connection monitor state is reset after a successful
           # websocket connection.
-          transmit ActiveSupport::JSON.encode(identifier: ActionCable::INTERNAL[:identifiers][:ping], type: ActionCable::INTERNAL[:message_types][:confirmation])
+          transmit type: ActionCable::INTERNAL[:message_types][:welcome]
         end
 
         def allow_request_origin?