pakyow-realtime 0.11.3 → 1.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 8bd4cd2aae232d43ce4107dc2641901c64470a1d
-  data.tar.gz: 76f0933e09a694a9092b60d94390942a0acc997f
+SHA256:
+  metadata.gz: e741f872b4f4c8c70d0b0435f69dea7a686e1d8ba95b3416ae89b8f3a50bd6a2
+  data.tar.gz: da45c2b4b7238ab709aeb7a243d6e2ee3f6869a86fc0d4d99e02a701960cc56a
 SHA512:
-  metadata.gz: 9c67add106eb7537aee27d8c9ffb004fbc0f57f60b4de299a2954236b356d135c45a120a080dce548e61506490f4368b0e0aafdda61ce6868eaf3bf5b14add02
-  data.tar.gz: ea16f4f8352e935015b8e175e1502d2fa1c683b1249a1cc3e7724da2dfa18188b3ff9b75c793950562537a6733dad24d59ae291ecf394bb5d0f199db3afa1411
+  metadata.gz: a44fd08cb285611e91b7129d266885ad30e6cecc02b33ba3b7bbacb36cee82228515437b027f305fa7cedd03af4c0c502be4a3b7d95ba9d0da83d60dc3b31576
+  data.tar.gz: 9524a3586f595db6a0c9d4f9538b9f8424be88aa627f8ad8f91030d1157ef9e84ee242ef9ca48ac2405f443a5a70d8b787e265c60c4ee4ca703064a0fb0dd1c4

data/{pakyow-realtime/CHANGELOG.md → CHANGELOG.md}

@@ -1,3 +1,8 @@
+# 1.0.0
+
+  * IMPROVED WebSocket reliability and performance.
+  * CHANGED WebSocket log level to verbose.
+
 # 0.11.0
 
   * Gracefully shuts down WebSocket when something bad happens

data/LICENSE

@@ -0,0 +1,4 @@
+Copyright (c) Metabahn, LLC
+
+Pakyow Realtime is an open-source project licensed under the terms of the LGPLv3 license.
+See <https://choosealicense.com/licenses/lgpl-3.0/> for license text.

data/{pakyow-realtime/README.md → README.md}

@@ -146,8 +146,7 @@ Source code can be downloaded as part of the Pakyow project on Github:
 
 # License
 
-Pakyow Realtime is released free and open-source under the [MIT
-License](http://opensource.org/licenses/MIT).
+Pakyow Realtime is free and open-source under the [LGPLv3 license](https://choosealicense.com/licenses/lgpl-3.0/).
 
 # Support
 

data/lib/pakyow/environment/realtime/config.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "pakyow/support/extension"
+
+module Pakyow
+  module Environment
+    module Realtime
+      module Config
+        extend Support::Extension
+
+        apply_extension do
+          configurable :realtime do
+            setting :server, true
+
+            setting :adapter, :memory
+            setting :adapter_settings, {}
+
+            defaults :production do
+              setting :adapter, :redis
+              setting :adapter_settings do
+                Pakyow.config.redis.to_h
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pakyow/realtime/actions/upgrader.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "pakyow/support/message_verifier"
+
+require "pakyow/realtime/websocket"
+
+module Pakyow
+  module Realtime
+    module Actions
+      class Upgrader
+        def call(connection)
+          if websocket?(connection)
+            WebSocket.new(connection.verifier.verify(connection.params[:id]), connection)
+            connection.halt
+          end
+        rescue Support::MessageVerifier::TamperedMessage
+          connection.status = 403
+          connection.halt
+        end
+
+        private
+
+        def websocket?(connection)
+          connection.path == "/pw-socket"
+        end
+      end
+    end
+  end
+end

data/lib/pakyow/realtime/behavior/config.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "pakyow/support/extension"
+
+module Pakyow
+  module Realtime
+    module Behavior
+      module Config
+        extend Support::Extension
+
+        apply_extension do
+          configurable :realtime do
+            setting :adapter_settings, {}
+            setting :path, "pw-socket"
+            setting :endpoint
+            setting :log_initial_request, false
+
+            defaults :production do
+              setting :adapter_settings do
+                { key_prefix: [Pakyow.config.redis.key_prefix, config.name].join("/") }
+              end
+
+              setting :log_initial_request, true
+            end
+
+            configurable :timeouts do
+              # Give sockets 60 seconds to connect before cleaning up their state.
+              #
+              setting :initial, 60
+
+              # When a socket disconnects, keep state around for 24 hours before
+              # cleaning up. This improves the user experience in cases such as
+              # when a browser window is left open on a sleeping computer.
+              #
+              setting :disconnect, 24 * 60 * 60
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pakyow/realtime/behavior/rendering/install_websocket.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "pakyow/support/extension"
+
+require "pakyow/presenter/view"
+
+module Pakyow
+  module Realtime
+    module Behavior
+      module Rendering
+        module InstallWebsocket
+          extend Support::Extension
+
+          apply_extension do
+            build do |view|
+              if head = view.head
+                head.append(Support::SafeStringHelpers.html_safe("<meta name=\"pw-socket\" ui=\"socket\">"))
+              end
+            end
+
+            attach do |presenter, app:|
+              presenter.render node: -> {
+                node = object.each_significant_node(:meta).find { |meta_node|
+                  meta_node.attributes[:name] == "pw-socket"
+                }
+
+                unless node.nil?
+                  Presenter::View.from_object(node)
+                end
+              } do
+                endpoint = app.config.realtime.endpoint
+
+                unless endpoint
+                  endpoint = if Pakyow.config.server.proxy
+                    # Connect directly to the app in development, since the proxy does not support websocket connections.
+                    #
+                    File.join("ws://#{Pakyow.config.server.host}:#{Pakyow.config.server.port}", app.config.realtime.path)
+                  else
+                    File.join("#{presentables[:__ws_protocol]}://#{presentables[:__ws_authority]}", app.config.realtime.path)
+                  end
+                end
+
+                attributes["data-ui"] = "socket(endpoint: #{endpoint}?id=#{presentables[:__verifier].sign(presentables[:__socket_client_id])})"
+              end
+            end
+
+            expose do |connection|
+              connection.set(:__verifier, connection.verifier)
+              connection.set(:__ws_protocol, connection.secure? ? "wss" : "ws")
+              connection.set(:__ws_authority, connection.authority)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pakyow/realtime/behavior/serialization.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+require "pakyow/support/extension"
+require "pakyow/support/serializer"
+
+module Pakyow
+  module Realtime
+    module Behavior
+      # Persists the in-memory realtime server across restarts.
+      #
+      module Serialization
+        extend Support::Extension
+
+        apply_extension do
+          on "shutdown", priority: :high do
+            if Pakyow.config.realtime.adapter == :memory && instance_variable_defined?(:@websocket_server)
+              realtime_server_serializer.serialize
+            end
+          end
+
+          after "boot" do
+            if Pakyow.config.realtime.adapter == :memory
+              realtime_server_serializer.deserialize
+            end
+          end
+        end
+
+        private def realtime_server_serializer
+          Support::Serializer.new(
+            @websocket_server.adapter,
+            name: "#{config.name}-realtime",
+            path: File.join(
+              Pakyow.config.root, "tmp", "state"
+            )
+          )
+        end
+      end
+    end
+  end
+end

data/lib/pakyow/realtime/behavior/server.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "pakyow/support/deep_freeze"
+require "pakyow/support/extension"
+
+require "pakyow/realtime/server"
+
+module Pakyow
+  module Realtime
+    module Behavior
+      module Server
+        extend Support::Extension
+
+        apply_extension do
+          extend Support::DeepFreeze
+          unfreezable :websocket_server
+          attr_reader :websocket_server
+
+          after "initialize", priority: :high do
+            @websocket_server = if is_a?(Plugin)
+              parent.websocket_server
+            else
+              Realtime::Server.new(
+                Pakyow.config.realtime.adapter,
+                Pakyow.config.realtime.adapter_settings.to_h.merge(
+                  config.realtime.adapter_settings.to_h
+                ),
+                config.realtime.timeouts
+              )
+            end
+          end
+
+          on "shutdown" do
+            if instance_variable_defined?(:@websocket_server)
+              @websocket_server.shutdown
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pakyow/realtime/behavior/silencing.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "pakyow/support/extension"
+
+module Pakyow
+  module Realtime
+    module Behavior
+      # Silences asset requests from being logged.
+      #
+      module Silencing
+        extend Support::Extension
+
+        apply_extension do
+          on "load" do
+            unless config.realtime.log_initial_request
+              Pakyow.silence do |connection|
+                connection.path.start_with?(File.join("/", config.realtime.path))
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pakyow/realtime/channel.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Pakyow
+  module Realtime
+    class Channel
+      class << self
+        def parse(qualified_channel)
+          Channel.new(*qualified_channel.split("::", 2))
+        end
+      end
+
+      attr_reader :name, :qualifier
+
+      def initialize(channel_name, qualifier = nil)
+        @name, @qualifier = channel_name, qualifier
+      end
+
+      def to_s
+        [@name, @qualifier].join("::")
+      end
+    end
+  end
+end

data/lib/pakyow/realtime/context.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Pakyow
+  module Realtime
+    # Deals with realtime connections in context of an app. Instances are
+    # returned by the `socket` helper method during routing.
+    #
+    # @api public
+    class Context
+      # @api private
+      def initialize(app)
+        @app = app
+      end
+
+      # Push a message down one or more channels.
+      #
+      # @api public
+      def push(msg, *channels)
+        delegate.push(msg, *channels)
+      end
+
+      # Push a message down a channel directed at a specific client,
+      # identified by key.
+      #
+      # @api public
+      def push_to_key(msg, channel, key, propagated: false)
+        delegate.push_to_key(msg, channel, key, propagated: propagated)
+      end
+
+      # Returns an instance of the connection delegate.
+      #
+      # @api private
+      def delegate
+        Delegate.instance
+      end
+    end
+  end
+end

data/lib/pakyow/realtime/framework.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "pakyow/framework"
+
+require "pakyow/realtime/helpers/broadcasting"
+require "pakyow/realtime/helpers/subscriptions"
+require "pakyow/realtime/helpers/socket"
+
+require "pakyow/realtime/behavior/config"
+require "pakyow/realtime/behavior/serialization"
+require "pakyow/realtime/behavior/server"
+require "pakyow/realtime/behavior/silencing"
+
+require "pakyow/realtime/actions/upgrader"
+
+require "pakyow/realtime/behavior/rendering/install_websocket"
+
+module Pakyow
+  module Realtime
+    class Framework < Pakyow::Framework(:realtime)
+      def boot
+        object.class_eval do
+          register_helper :active, Helpers::Broadcasting
+          register_helper :active, Helpers::Subscriptions
+          register_helper :passive, Helpers::Socket
+
+          # Socket events are triggered on the app.
+          #
+          events :join, :leave
+
+          include Behavior::Config
+          include Behavior::Server
+          include Behavior::Silencing
+          include Behavior::Serialization
+
+          isolated :Renderer do
+            include Behavior::Rendering::InstallWebsocket
+          end
+
+          isolated :Connection do
+            after "initialize" do
+              set(:__socket_client_id, params[:socket_client_id] || Support::MessageVerifier.key)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pakyow/realtime/helpers/broadcasting.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Pakyow
+  module Realtime
+    module Helpers
+      module Broadcasting
+        def broadcast(message)
+          app.websocket_server.subscription_broadcast(socket_client_id, message)
+        end
+      end
+    end
+  end
+end

data/lib/pakyow/realtime/helpers/socket.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Pakyow
+  module Realtime
+    module Helpers
+      module Socket
+        def socket_client_id
+          @connection.get(:__socket_client_id)
+        end
+      end
+    end
+  end
+end

data/lib/pakyow/realtime/helpers/subscriptions.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "pakyow/realtime/channel"
+
+module Pakyow
+  module Realtime
+    module Helpers
+      module Subscriptions
+        def subscribe(channel, *qualifiers)
+          channels = if qualifiers.empty?
+            Channel.new(channel)
+          else
+            qualifiers.map { |qualifier|
+              Channel.new(channel, qualifier)
+            }
+          end
+
+          app.websocket_server.socket_subscribe(socket_client_id, *channels)
+        end
+
+        def unsubscribe(channel, *qualifiers)
+          channels = if qualifiers.empty?
+            Channel.new(channel, "*")
+          else
+            qualifiers.map { |qualifier|
+              Channel.new(channel, qualifier)
+            }
+          end
+
+          app.websocket_server.socket_unsubscribe(*channels)
+        end
+      end
+    end
+  end
+end

data/lib/pakyow/realtime/server/adapters/memory.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "concurrent/array"
+require "concurrent/hash"
+require "concurrent/scheduled_task"
+
+module Pakyow
+  module Realtime
+    class Server
+      module Adapters
+        # Manages websocket channels in memory.
+        #
+        # Great for development, not for use in production!
+        #
+        # @api private
+        class Memory
+          def initialize(server, _config)
+            @server = server
+
+            @socket_ids_by_channel = Concurrent::Hash.new
+            @channels_by_socket_id = Concurrent::Hash.new
+            @expirations_for_socket_id = Concurrent::Hash.new
+            @socket_instances_by_socket_id = Concurrent::Hash.new
+          end
+
+          def connect
+            # intentionally empty
+          end
+
+          def disconnect
+            # intentionally empty
+          end
+
+          def socket_subscribe(socket_id, *channels)
+            channels.each do |channel|
+              channel = channel.to_s.to_sym
+              (@socket_ids_by_channel[channel] ||= Concurrent::Array.new) << socket_id
+              (@channels_by_socket_id[socket_id] ||= Concurrent::Array.new) << channel
+            end
+          end
+
+          def socket_unsubscribe(*channels)
+            channels.each do |channel|
+              channel = Regexp.new(channel.to_s)
+
+              @socket_ids_by_channel.select { |key|
+                key.to_s.match?(channel)
+              }.each do |key, socket_ids|
+                @socket_ids_by_channel.delete(key)
+
+                socket_ids.each do |socket_id|
+                  @channels_by_socket_id[socket_id]&.delete(key)
+                end
+              end
+            end
+          end
+
+          def subscription_broadcast(channel, message)
+            @server.transmit_message_to_connection_ids(message, socket_ids_for_channel(channel))
+          end
+
+          def expire(socket_id, seconds)
+            task = Concurrent::ScheduledTask.execute(seconds) {
+              channels_for_socket_id(socket_id).each do |channel|
+                @channels_by_socket_id.delete(socket_id)
+                @socket_ids_by_channel[channel].delete(socket_id)
+                @socket_instances_by_socket_id.delete(socket_id)
+              end
+            }
+
+            @expirations_for_socket_id[socket_id] ||= []
+            @expirations_for_socket_id[socket_id] << task
+          end
+
+          def persist(socket_id)
+            (@expirations_for_socket_id[socket_id] || []).each(&:cancel)
+            @expirations_for_socket_id.delete(socket_id)
+          end
+
+          def expiring?(socket_id)
+            @expirations_for_socket_id[socket_id]&.any?
+          end
+
+          def current!(socket_id, socket_instance_id)
+            @socket_instances_by_socket_id[socket_id] = socket_instance_id
+          end
+
+          def current?(socket_id, socket_instance_id)
+            @socket_instances_by_socket_id[socket_id] == socket_instance_id
+          end
+
+          SERIALIZABLE_IVARS = %i(
+            @socket_ids_by_channel
+            @channels_by_socket_id
+            @socket_instances_by_socket_id
+          ).freeze
+
+          def serialize
+            SERIALIZABLE_IVARS.each_with_object({}) do |ivar, hash|
+              hash[ivar] = instance_variable_get(ivar)
+            end
+          end
+
+          protected
+
+          def socket_ids_for_channel(channel)
+            channel = Regexp.new(channel.to_s)
+
+            @socket_ids_by_channel.select { |key|
+              key.to_s.match?(channel)
+            }.each_with_object([]) do |(_, socket_ids_for_channel), socket_ids|
+              socket_ids.concat(
+                socket_ids_for_channel.reject { |socket_id|
+                  expiring?(socket_id)
+                }
+              )
+            end
+          end
+
+          def channels_for_socket_id(socket_id)
+            @channels_by_socket_id[socket_id] || []
+          end
+        end
+      end
+    end
+  end
+end