monkrb 0.17.0 → 0.19.0

data/lib/monk/websocket/redis_fanout.rb

@@ -1,5 +1,7 @@
 require "redis"
 require "securerandom"
+require_relative "errors"
+require_relative "listeners"
 
 module Monk
   module WebSocket
@@ -9,7 +11,7 @@ module Monk
     # LISTEN/NOTIFY per docs/design/websocket.md Open Question 3).
     #
     # Wraps a Registry with the same public interface (#register,
-    # #unregister, #count, #broadcast), so an app swaps which object it
+    # #unregister, #count, #broadcast, #listen!), so an app swaps which object it
     # holds and nothing else changes. #broadcast still delivers to this
     # process's local Registry directly -- same latency and reliability as
     # a plain Registry if Redis is briefly unavailable -- and additionally
@@ -41,13 +43,43 @@ module Monk
         @redis_url = redis_url.dup.freeze
         @origin = SecureRandom.uuid.freeze
 
+        # No live connection lives on this object -- #listen! runs its
+        # subscriber in a Ractor of its own, and #publisher below opens one
+        # client per Ractor, lazily -- so there's nothing left unshareable
+        # and this instance can freeze itself the same way Registry does.
+        # That matters for real use: an app holds this behind a module
+        # constant (e.g. ChatServer::REGISTRY, mirroring Registry's own
+        # existing usage) read from every connection's own Ractor, which
+        # raises Ractor::IsolationError unless the constant's value is
+        # shareable.
+        freeze
+      end
+
+      # Starts relaying other processes' broadcasts into this process's
+      # registry: a subscriber Ractor with its own Redis connection. Only
+      # the process that holds sockets calls this (bin/websocket_server, at
+      # boot, from the main Ractor) -- a publish-only process (bin/server,
+      # bin/jobs) never does, so it holds no subscriber connection at all.
+      # Returns once the psubscribe is in effect, so nothing broadcast
+      # after it can be missed; raises ListenError if Redis can't be
+      # reached. Calling it again is a no-op.
+      def listen!
+        return self if Listeners.listening?(@origin)
+
+        ready = Ractor::Port.new
         # Ractor.new's block args must be shareable: registry is (Registry
         # freezes itself around a Ractor, which is inherently shareable),
-        # redis_url and @origin are plain frozen Strings. The Redis client
-        # itself is built inside the block, never passed in -- mirrors
-        # PG::Connection's per-Ractor pattern (persistence/pg.rb).
-        @subscriber = Ractor.new(registry, @redis_url, @origin) do |registry, url, origin|
+        # the URL and origin are frozen Strings, a Port always is. The
+        # Redis client itself is built inside the block, never passed in --
+        # mirrors PG::Connection's per-Ractor pattern (persistence/pg.rb).
+        Ractor.new(@registry, @redis_url, @origin, ready) do |registry, url, origin, ready|
+          subscribed = false
           Redis.new(url: url).psubscribe("#{Monk::WebSocket::RedisFanout::CHANNEL_PREFIX}*") do |on|
+            on.psubscribe do
+              subscribed = true
+              ready.send(:ok)
+            end
+
             on.pmessage do |_pattern, channel, envelope|
               sender, payload = envelope.split("\0", 2)
               next if sender == origin
@@ -66,19 +98,30 @@ module Monk
               registry.broadcast(key, payload)
             end
           end
+        rescue StandardError => e
+          raise if subscribed
+
+          ready.send("#{e.class}: #{e.message}")
         end
 
-        # No live connection lives on this object -- #publisher below opens
-        # one per Ractor, lazily -- so there's nothing left unshareable and
-        # this instance can freeze itself the same way Registry does. That
-        # matters for real use: an app holds this behind a module constant
-        # (e.g. ChatServer::REGISTRY, mirroring Registry's own existing
-        # usage) read from every connection's own Ractor, which raises
-        # Ractor::IsolationError unless the constant's value is shareable.
-        freeze
+        result = ready.receive
+        raise ListenError, "Monk::WebSocket::RedisFanout#listen! couldn't subscribe: #{result}" unless result == :ok
+
+        Listeners.add(@origin)
+        self
+      end
+
+      def register(key, port)
+        unless Listeners.listening?(@origin)
+          raise NotListeningError,
+            "Monk::WebSocket::RedisFanout#register before #listen!: this socket would never get " \
+            "other processes' broadcasts -- call listen! once at boot in the process that holds " \
+            "sockets (bin/websocket_server: Monk::Live.listen!)"
+        end
+
+        @registry.register(key, port)
       end
 
-      def register(key, port) = @registry.register(key, port)
       def unregister(key, port) = @registry.unregister(key, port)
       def count(key) = @registry.count(key)
 

data/lib/monk/websocket/registry.rb

@@ -67,6 +67,12 @@ module Monk
         ask(:count, key, nil)
       end
 
+      # Nothing to listen to: every broadcast reaching this registry comes
+      # from this process. Here so a WS process calls #listen! the same
+      # way whether it holds a Registry or a RedisFanout/PgFanout around
+      # one.
+      def listen! = self
+
       private
 
       def ask(op, key, arg)

data/lib/monk/websocket/server.rb

@@ -25,9 +25,20 @@ module Monk
       # docs/history/chat-gap-analysis.md) -- authenticate: true only checks the
       # credential once, at the handshake, so a session revoked or
       # expired afterward would otherwise leave the socket live
-      # indefinitely. Requires authenticate: true (there's no credential
-      # to reverify without it) and defaults to nil (disabled), same as
-      # ping_interval:.
+      # indefinitely. Requires authenticate: true or :optional (there's no
+      # credential to reverify without it) and defaults to nil (disabled),
+      # same as ping_interval:. Under :optional it watches only the
+      # connections that have a session.
+      #
+      # authenticate: :optional is the middle mode (docs/design/websocket.md,
+      # "Anonymous connections"): a connection with a valid session gets its
+      # subject, and one without -- no credential, or a revoked or expired
+      # one -- comes in anonymous (subject nil) instead of being refused.
+      # What an anonymous connection may then do is the handler's call:
+      # Monk::Live's rules deny it everything a rule doesn't open with
+      # `anonymous: true`. The Origin check still applies: to a cookie, as
+      # under true, and to an anonymous connection that sends an Origin,
+      # since only a browser does.
       #
       # max_payload_size: (bytes) -- see Connection::DEFAULT_MAX_PAYLOAD_SIZE
       # for what it guards against (gap 5). Unlike ping_interval:/
@@ -35,6 +46,11 @@ module Monk
       # hostile client on a public endpoint, not an opt-in behavior
       # change, so a server that doesn't mention it still gets the
       # default cap rather than no cap at all.
+      AUTHENTICATE_MODES = [false, true, :optional].freeze
+
+      # The signals #run treats as "stop": Ctrl+C and TERM.
+      STOP_SIGNALS = [Signal.list.fetch("INT"), Signal.list.fetch("TERM")].freeze
+
       def initialize(
         port:, bind: "0.0.0.0", allowed_origins: nil, authenticate: false, ping_interval: nil,
         reverify_interval: nil, max_payload_size: Connection::DEFAULT_MAX_PAYLOAD_SIZE
@@ -43,11 +59,15 @@ module Monk
           raise ArgumentError, "ping_interval must be positive, got #{ping_interval.inspect}"
         end
 
+        unless AUTHENTICATE_MODES.include?(authenticate)
+          raise ArgumentError, "authenticate must be false, true or :optional, got #{authenticate.inspect}"
+        end
+
         if reverify_interval
           unless reverify_interval.positive?
             raise ArgumentError, "reverify_interval must be positive, got #{reverify_interval.inspect}"
           end
-          raise ArgumentError, "reverify_interval requires authenticate: true" unless authenticate
+          raise ArgumentError, "reverify_interval requires authenticate: true or :optional" unless authenticate
         end
 
         unless max_payload_size.positive?
@@ -57,8 +77,8 @@ module Monk
         if authenticate
           unless defined?(Monk::Auth) && Monk::Auth.config
             raise Monk::AuthNotConfiguredError,
-              "Monk::WebSocket::Server.new(authenticate: true) requires Monk::Auth to already be " \
-              "configured -- call Monk::Auth.configure first"
+              "Monk::WebSocket::Server.new(authenticate: #{authenticate.inspect}) requires Monk::Auth to " \
+              "already be configured -- call Monk::Auth.configure first"
           end
 
           # Monk::Auth's config is a plain, unfrozen Hash until this runs
@@ -107,15 +127,22 @@ module Monk
           end
           ractor.send(socket, move: true)
         end
-      rescue Interrupt
-        # Ctrl+C's default Ruby behavior: raise Interrupt in the thread
-        # blocked in the syscall, here TCPServer#accept. Unrescued, that's
-        # an unhandled exception -- Ruby prints its backtrace and exits
-        # non-zero, which reads as a crash even though this is the normal,
-        # intended way to stop a long-running server. Registry#ask's
-        # Ractor::ClosedError rescue (registry.rb) guards a different
-        # failure point in this same shutdown -- a live connection's
-        # cleanup racing the registry Ractor's teardown -- not this one.
+      rescue SignalException => e
+        raise unless STOP_SIGNALS.include?(e.signo)
+
+        # Ctrl+C (INT, raised as Interrupt) and TERM (what docker stop,
+        # Kubernetes, Fly, Render and systemd send on every deploy) both
+        # land here: Ruby raises them in the thread blocked in
+        # TCPServer#accept. Unrescued, INT prints a backtrace and TERM ends
+        # the process by the signal (exit 143) -- either reads as a crash
+        # though it's the normal way to stop a long-running server. Here
+        # the server stops accepting and #run returns, so the script ends
+        # with exit 0, as bin/server and bin/jobs do. Open connections are
+        # dropped when the process exits, with no close frame
+        # (docs/design/websocket.md, "Stopping the server").
+        # Registry#ask's Ractor::ClosedError rescue (registry.rb) guards a
+        # different failure point in this same shutdown -- a live
+        # connection's cleanup racing the registry Ractor's teardown.
         @tcp_server.close
       end
 
@@ -138,9 +165,14 @@ module Monk
           end
 
         subject = nil
-        if authenticate
+        case authenticate
+        when true
           subject = authenticate!(socket, headers, allowed_origins)
           return unless subject
+        when :optional
+          return unless origin_allowed_for_optional?(socket, headers, allowed_origins)
+
+          subject = identify(headers)
         end
 
         socket.write(Handshake.response_for(request))
@@ -148,7 +180,7 @@ module Monk
         connection = Connection.new(socket, subject: subject, max_payload_size: max_payload_size)
         connection.start_heartbeat(ping_interval) if ping_interval
         reverify_thread =
-          if reverify_interval
+          if reverify_interval && subject
             start_reverify(connection, Handshake.credential_from(headers)[:token], reverify_interval)
           end
         begin
@@ -194,6 +226,34 @@ module Monk
       end
       private_class_method :authenticate!
 
+      # authenticate: :optional's Origin check, before anything is verified.
+      # A Bearer connection is exempt, as under true. A cookie needs an
+      # allowed Origin, as under true. An anonymous connection that sends an
+      # Origin needs an allowed one too: only a browser sends it, and this
+      # stops another site's page from opening sockets here on its
+      # visitors' behalf; one that sends none (not a browser) gets in.
+      # Writes the 403 itself and returns false when refused.
+      def self.origin_allowed_for_optional?(socket, headers, allowed_origins)
+        return true unless allowed_origins
+
+        credential = Handshake.credential_from(headers)
+        return true if credential&.fetch(:via) == :bearer
+
+        origin = headers["origin"]
+        allowed = credential ? origin && allowed_origins.include?(origin) : origin.nil? || allowed_origins.include?(origin)
+        socket.write("HTTP/1.1 403 Forbidden\r\n\r\n") unless allowed
+        allowed
+      end
+      private_class_method :origin_allowed_for_optional?
+
+      # The subject of a valid session, or nil -- no credential, or one
+      # Monk::Auth no longer accepts, both mean anonymous under :optional.
+      def self.identify(headers)
+        credential = Handshake.credential_from(headers)
+        credential && Monk::Auth.verify(credential[:token])
+      end
+      private_class_method :identify
+
       # Sleeps in `interval`-sized steps, re-running Monk::Auth.verify
       # against the same raw credential each time, until it comes back
       # nil (revoked or expired) -- then closes the connection with the

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: monkrb
 version: !ruby/object:Gem::Version
-  version: 0.17.0
+  version: 0.19.0
 platform: ruby
 authors:
 - Matteo Folin
@@ -176,6 +176,14 @@ files:
 - lib/monk/environment.rb
 - lib/monk/errors.rb
 - lib/monk/freeze_hooks.rb
+- lib/monk/jobs.rb
+- lib/monk/jobs/adapters/pg.rb
+- lib/monk/jobs/args.rb
+- lib/monk/jobs/claim.rb
+- lib/monk/jobs/errors.rb
+- lib/monk/jobs/job.rb
+- lib/monk/jobs/runtime.rb
+- lib/monk/jobs/worker.rb
 - lib/monk/live.rb
 - lib/monk/live/client/idiomorph.LICENSE
 - lib/monk/live/client/idiomorph.js
@@ -192,6 +200,7 @@ files:
 - lib/monk/mail.rb
 - lib/monk/mail/address.rb
 - lib/monk/mail/errors.rb
+- lib/monk/mail/later.rb
 - lib/monk/mail/message.rb
 - lib/monk/mail/mime.rb
 - lib/monk/mail/transports.rb
@@ -206,29 +215,44 @@ files:
 - lib/monk/scaffold.rb
 - lib/monk/settings.rb
 - lib/monk/state_ractor.rb
+- lib/monk/templates/auth/app/mailers/app_mailer.rb
+- lib/monk/templates/auth/app/views/mail/magic_link.erb
 - lib/monk/templates/auth/config/auth.rb
 - lib/monk/templates/auth/db/migrate/00000000000001_create_auth_tables.down.sql
 - lib/monk/templates/auth/db/migrate/00000000000001_create_auth_tables.up.sql
-- lib/monk/templates/auth/views/mail/magic_link.erb
 - lib/monk/templates/base/.dockerignore
 - lib/monk/templates/base/.gitignore
 - lib/monk/templates/base/.ruby-version
 - lib/monk/templates/base/Dockerfile
 - lib/monk/templates/base/Gemfile
+- lib/monk/templates/base/app/app.rb
+- lib/monk/templates/base/app/broadcasts/.keep
+- lib/monk/templates/base/app/helpers/.keep
+- lib/monk/templates/base/app/jobs/.keep
+- lib/monk/templates/base/app/mailers/.keep
+- lib/monk/templates/base/app/models/.keep
+- lib/monk/templates/base/app/presenters/.keep
+- lib/monk/templates/base/app/views/index.erb
+- lib/monk/templates/base/app/views/layouts/app.erb
 - lib/monk/templates/base/bin/server
 - lib/monk/templates/base/bin/websocket_server
 - lib/monk/templates/base/config.ru
+- lib/monk/templates/base/config/load.rb
 - lib/monk/templates/base/config/settings.rb
 - lib/monk/templates/base/public/css/app.css
 - lib/monk/templates/base/public/js/app.js
-- lib/monk/templates/base/views/index.erb
-- lib/monk/templates/base/views/layouts/app.erb
+- lib/monk/templates/jobs/app/jobs/hello_job.rb
+- lib/monk/templates/jobs/app/jobs/send_login_link.rb
+- lib/monk/templates/jobs/bin/jobs
+- lib/monk/templates/jobs/config/jobs.rb
+- lib/monk/templates/jobs/db/migrate/00000000000002_create_jobs_tables.down.sql
+- lib/monk/templates/jobs/db/migrate/00000000000002_create_jobs_tables.up.sql
+- lib/monk/templates/live/app/app.rb
+- lib/monk/templates/live/app/views/index.erb
+- lib/monk/templates/live/app/views/live/_hits.erb
 - lib/monk/templates/live/bin/websocket_server
-- lib/monk/templates/live/config.ru
 - lib/monk/templates/live/config/live.rb
 - lib/monk/templates/live/config/live_pg.rb
-- lib/monk/templates/live/views/index.erb
-- lib/monk/templates/live/views/live/_hits.erb
 - lib/monk/templates/mail/Gemfile.extra
 - lib/monk/templates/mail/config/mail.rb
 - lib/monk/templates/postgres/Dockerfile
@@ -245,6 +269,7 @@ files:
 - lib/monk/websocket/errors.rb
 - lib/monk/websocket/frame.rb
 - lib/monk/websocket/handshake.rb
+- lib/monk/websocket/listeners.rb
 - lib/monk/websocket/pg_fanout.rb
 - lib/monk/websocket/redis_fanout.rb
 - lib/monk/websocket/registry.rb