ruflet_server 0.0.18 → 0.0.20

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9009d8e648b2101fcaf583feae53f3f5f6d9d8975849960d44c87f9a37f23597
-  data.tar.gz: 58d04690e2b0395698a343722a5e0e7c69bb351c918a2979f11d47f7e14d95ab
+  metadata.gz: c8ce7c65f8922fb96c632f08c3fbbfbe5ab4d2f51ef010aca2938dada94bbb06
+  data.tar.gz: '09a16364d80b69210248753a9eeb062a8d895be2cfa02844bd7850a96c4392d4'
 SHA512:
-  metadata.gz: bfff7024cc42755729901dca5fbfe79b494c9167aecd40e01a65b153614dc004394406a2b6fe56844b88fbfce84fdd66b3ee08e250b8b11edeed5d34c652adb6
-  data.tar.gz: f958db4dacb8d0b6a17b1523e51e72e8374cb39c9eb32e69646d822cd6c2b7fa79a347ef1bde5fca3e71abfeeecdb0228fdec7f4936916e3d389ca1db52fc557
+  metadata.gz: 0efb74cd09d74eb058e0cfbdaa3027483fb809552e15109070a80e3bad364f9d9d297173249033df16029c2f6c366ee24db3e40848d1adf7fa583927b4fe7a83
+  data.tar.gz: 908da326003ca5cfff54b1a608148afaf0f557c8d9871c602e8234abe6710b6e79c27f0f0de0b9bcda78368ec67735d62ba31b41f84af9f6b551791bde15a889

data/README.md

@@ -1,3 +1,17 @@
 # ruflet_server
 
-Part of Ruflet monorepo.
+`ruflet_server` runs server-driven Ruflet applications and connects their Ruby
+UI code to Ruflet clients.
+
+It is installed automatically in projects created with `ruflet new`. Start an
+application through the Ruflet CLI:
+
+```bash
+ruflet run
+ruflet run --web
+ruflet run --desktop
+```
+
+Application code uses the public `Ruflet.run` API supplied by `ruflet_core`.
+Rails applications should use `ruflet_rails` instead of starting this server
+directly.

data/lib/ruflet/server/connection_protocol.rb

@@ -0,0 +1,285 @@
+# frozen_string_literal: true
+
+module Ruflet
+  # Transport-agnostic implementation of the Ruflet wire protocol: one
+  # connection loop shared by every server that speaks to Flutter clients.
+  #
+  # The standalone TCP server (Ruflet::Server) and host-server adapters such
+  # as ruflet_rails' Rack-hijack endpoint include this module and provide
+  # only their transport plus the integration hooks below — the protocol
+  # itself is never reimplemented.
+  #
+  # Includers must initialize:
+  #   @app_block       — proc invoked with the Page on first registration
+  #   @sessions        — Hash mapping connection key => Page
+  #   @sessions_mutex  — Mutex guarding @sessions
+  module ConnectionProtocol
+    # ------------------------------------------------------------------
+    # Integration hooks (override in the including server as needed).
+    # ------------------------------------------------------------------
+
+    # Called when a connection enters the protocol loop.
+    def connection_opened(ws); end
+
+    # Called when a connection leaves the protocol loop.
+    def connection_closed(ws); end
+
+    # Return an existing Page to resume for this session id, or nil to
+    # create a fresh one (hosts with a session registry override this).
+    def resume_session(_session_id)
+      nil
+    end
+
+    # Called after a Page is stored for a connection.
+    def session_stored(page, ws); end
+
+    # Called after a Page is removed for a connection.
+    def session_removed(page, ws); end
+
+    # Called before a control event is dispatched to the Page.
+    def before_dispatch_event(ws, event); end
+
+    def log_connection_error(error)
+      warn "server error: #{error.class}: #{error.message}"
+      warn error.backtrace.join("\n") if error.backtrace
+    end
+
+    # ------------------------------------------------------------------
+    # Transport entry points.
+    # ------------------------------------------------------------------
+
+    # For hosts that already performed the HTTP upgrade (Rack hijack, the
+    # embedded runtime, tests with socket pairs).
+    def handle_upgraded_socket(io)
+      run_connection(Ruflet::WebSocketConnection.new(io))
+    end
+
+    def run_connection(ws)
+      connection_opened(ws)
+
+      while (raw = ws.read_message)
+        handle_message(ws, raw)
+      end
+    rescue StandardError => e
+      return if disconnect_error?(e)
+
+      log_connection_error(e)
+      send_message(ws, Protocol::ACTIONS[:session_crashed], { "message" => e.message.to_s.dup.force_encoding("UTF-8") })
+    ensure
+      close_connection(ws)
+    end
+
+    def close_connection(ws)
+      return unless ws
+
+      remove_session(ws)
+      connection_closed(ws)
+      ws.close
+    end
+
+    # ------------------------------------------------------------------
+    # Protocol core.
+    # ------------------------------------------------------------------
+
+    def handle_message(ws, raw)
+      action, payload = decode_incoming(raw)
+      payload ||= {}
+
+      warn "incoming action=#{action.inspect}" if ENV["RUFLET_DEBUG"] == "1"
+
+      case action
+      when Protocol::ACTIONS[:register_client], Protocol::ACTIONS[:register_web_client]
+        on_register_client(ws, payload)
+      when Protocol::ACTIONS[:control_event], Protocol::ACTIONS[:page_event_from_web]
+        on_control_event(ws, payload)
+      when Protocol::ACTIONS[:update_control], Protocol::ACTIONS[:update_control_props]
+        on_update_control(ws, payload)
+      when Protocol::ACTIONS[:invoke_control_method]
+        on_invoke_control_method(ws, payload)
+      else
+        raise "Unknown action: #{action.inspect}"
+      end
+    end
+
+    def decode_incoming(raw)
+      parsed = normalize_incoming(Ruflet::WireCodec.unpack(raw.to_s.b))
+
+      if parsed.is_a?(Array) && parsed.length >= 2
+        return [parsed[0], parsed[1]]
+      end
+
+      if parsed.is_a?(Hash)
+        action = parsed["action"] || parsed[:action]
+        payload = parsed["payload"] || parsed[:payload]
+        return [action, payload] unless action.nil?
+
+        if (parsed.key?("target") || parsed.key?(:target)) && (parsed.key?("name") || parsed.key?(:name))
+          return [Protocol::ACTIONS[:control_event], parsed]
+        end
+      end
+
+      raise "Unsupported payload format"
+    end
+
+    def normalize_incoming(value)
+      case value
+      when String
+        value.dup.force_encoding("UTF-8")
+      when Integer, Float, TrueClass, FalseClass, NilClass
+        value
+      when Symbol
+        value.to_s
+      when Array
+        value.map { |v| normalize_incoming(v) }
+      when Hash
+        value.each_with_object({}) do |(k, v), out|
+          out[k.to_s] = normalize_incoming(v)
+        end
+      else
+        value.to_s
+      end
+    end
+
+    def on_register_client(ws, payload)
+      normalized = Protocol.normalize_register_payload(payload)
+      session_id = normalized["session_id"].to_s.empty? ? pseudo_uuid : normalized["session_id"]
+
+      page = resume_session(session_id)
+      first_registration = page.nil?
+
+      if page
+        attach_sender(page, ws)
+        reset_mount_state(page)
+      else
+        page = Page.new(
+          session_id: session_id,
+          client_details: normalized,
+          sender: sender_for(ws)
+        )
+        page.title = "Ruflet App"
+      end
+
+      @sessions_mutex.synchronize { @sessions[ws.session_key] = page }
+      session_stored(page, ws)
+
+      initial_response = [
+        Protocol::ACTIONS[:register_client],
+        Protocol.register_response(session_id: session_id)
+      ]
+      ws.send_binary(Ruflet::WireCodec.pack(initial_response))
+
+      @app_block.call(page) if first_registration
+      page.update
+    rescue StandardError => e
+      send_message(ws, Protocol::ACTIONS[:session_crashed], { "message" => e.message.to_s })
+      raise
+    end
+
+    def on_control_event(ws, payload)
+      event = Protocol.normalize_control_event_payload(payload)
+      page = fetch_page(ws)
+      return if event["target"].nil? || event["name"].to_s.empty?
+
+      attach_sender(page, ws)
+      before_dispatch_event(ws, event)
+      page.dispatch_event(
+        target: event["target"],
+        name: event["name"],
+        data: normalize_event_data(event["data"])
+      )
+    end
+
+    def on_update_control(ws, payload)
+      update = Protocol.normalize_update_control_payload(payload)
+      page = fetch_page(ws)
+      return if update["id"].nil?
+
+      attach_sender(page, ws)
+      page.apply_client_update(update["id"], update["props"] || {})
+    end
+
+    def on_invoke_control_method(ws, payload)
+      page = fetch_page(ws)
+      attach_sender(page, ws)
+      page.handle_invoke_method_result(Protocol.normalize_invoke_method_result_payload(payload))
+    end
+
+    def fetch_page(ws)
+      page = @sessions_mutex.synchronize { @sessions[ws.session_key] }
+      raise "Session not found" unless page
+
+      page
+    end
+
+    def remove_session(ws)
+      return unless ws
+
+      page = @sessions_mutex.synchronize { @sessions.delete(ws.session_key) }
+      session_removed(page, ws) if page
+      page
+    end
+
+    def normalize_event_data(value)
+      case value
+      when Hash
+        value.each_with_object({}) { |(k, v), out| out[k.to_sym] = normalize_event_data(v) }
+      when Array
+        value.map { |entry| normalize_event_data(entry) }
+      else
+        value
+      end
+    end
+
+    def send_message(ws, action, payload)
+      return if ws.nil? || ws.closed?
+
+      ws.send_binary(Ruflet::WireCodec.pack([action, payload]))
+    rescue StandardError => e
+      log_connection_error(e) unless disconnect_error?(e)
+      remove_session(ws)
+      connection_closed(ws)
+      nil
+    end
+
+    def sender_for(ws)
+      lambda do |action, msg_payload|
+        send_message(ws, action, msg_payload)
+      end
+    end
+
+    def attach_sender(page, ws)
+      page.instance_variable_set(:@sender, sender_for(ws))
+    end
+
+    def reset_mount_state(page)
+      page.instance_variable_set(:@overlay_container_mounted, false)
+      page.instance_variable_set(:@dialogs_container_mounted, false)
+      page.instance_variable_set(:@services_container_mounted, false)
+    end
+
+    def disconnect_error?(error)
+      return true if error.is_a?(IOError)
+      return true if error.is_a?(Errno::EPIPE)
+      return true if error.is_a?(Errno::ECONNRESET)
+      return true if error.is_a?(Errno::ECONNABORTED)
+      return true if error.is_a?(Errno::ENOTCONN)
+      return true if error.is_a?(Errno::ESHUTDOWN)
+      return true if error.is_a?(Errno::EBADF)
+      return true if error.is_a?(Errno::EINVAL)
+
+      false
+    end
+
+    def pseudo_uuid
+      now = Process.clock_gettime(Process::CLOCK_REALTIME, :nanosecond)
+      rnd = rand(0..0xffff_ffff)
+      "%08x-%04x-%04x-%04x-%012x" % [
+        rnd,
+        now & 0xffff,
+        (now >> 16) & 0xffff,
+        (now >> 32) & 0xffff,
+        (now >> 48) & 0xffff_ffff_ffff
+      ]
+    end
+  end
+end

data/lib/ruflet/server.rb

@@ -124,21 +124,50 @@ module Ruflet
         ws = @connections_mutex.synchronize { @connections[session_key] }
         next unless ws
 
-        refreshed_page = Page.new(
-          session_id: current_page.session_id,
-          client_details: current_page.client_details,
-          sender: lambda do |action, payload|
-            send_message(ws, action, payload)
+        # Open dialogs, sheets, and snack bars are Navigator routes on the
+        # client; replacing the control tree does not pop them. Close them
+        # first, otherwise a reload while an overlay is open leaves it on
+        # screen wired to control ids the reloaded page cannot resolve.
+        begin
+          nil while current_page.respond_to?(:close_dialog) && current_page.close_dialog
+        rescue StandardError
+          nil
+        end
+
+        if current_page.respond_to?(:reset_for_reload!)
+          # Re-render on the live page. The client's overlay/service/dialogs
+          # containers stay mounted; a recreated Page would re-send them,
+          # replacing their client-side instances and detaching them — after
+          # which dialog and service patches are silently ignored.
+          current_page.reset_for_reload!
+          @app_block.call(current_page)
+          # Clear page-level chrome the reloaded block dropped and flush the
+          # overlay (appbar/drawer/FAB live in the view and rebuild wholesale;
+          # page props and the mounted overlay need explicit updates).
+          current_page.finalize_reload! if current_page.respond_to?(:finalize_reload!)
+          # Keeps route-driven apps on their current route: replays the
+          # route_change event when the block did not route itself.
+          current_page.replay_route_after_reload! if current_page.respond_to?(:replay_route_after_reload!)
+          current_page.update
+        else
+          # Older ruflet_core without reset_for_reload!: fall back to a fresh
+          # page (loses client-side container bindings until reconnect).
+          refreshed_page = Page.new(
+            session_id: current_page.session_id,
+            client_details: current_page.client_details,
+            sender: lambda do |action, payload|
+              send_message(ws, action, payload)
+            end
+          )
+          refreshed_page.title = "Ruflet App"
+
+          @sessions_mutex.synchronize do
+            @sessions[session_key] = refreshed_page
           end
-        )
-        refreshed_page.title = "Ruflet App"
 
-        @sessions_mutex.synchronize do
-          @sessions[session_key] = refreshed_page
+          @app_block.call(refreshed_page)
+          refreshed_page.update
         end
-
-        @app_block.call(refreshed_page)
-        refreshed_page.update
       rescue StandardError => e
         warn "reload error: #{e.class}: #{e.message}"
       end
@@ -155,7 +184,10 @@ module Ruflet
 
     def trap_signal(signal_name)
       Signal.trap(signal_name) do
-        stop
+        # Trap context restricts Mutex use, so calling stop here raises
+        # ThreadError and the signal is silently swallowed. Only unwind the
+        # main thread; start's ensure performs the actual stop outside the
+        # trap context.
         Thread.main.raise(Interrupt)
       rescue StandardError
         nil
@@ -324,14 +356,17 @@ module Ruflet
     end
 
     def handle_http_request(socket, path)
-      case path
+      request_path = path.to_s.split("?", 2).first.to_s
+      return if serve_web_client(socket, request_path)
+
+      case request_path
       when "/health"
         write_http_response(socket, 200, "text/plain", "ok")
       when "/"
         write_http_response(socket, 200, "text/plain", "ruflet server")
       else
-        if path.start_with?("/assets/")
-          serve_asset(socket, path)
+        if request_path.start_with?("/assets/")
+          serve_asset(socket, request_path)
         else
           write_http_response(socket, 404, "text/plain", "not found")
         end
@@ -341,6 +376,37 @@ module Ruflet
       write_http_response(socket, 500, "text/plain", "server error")
     end
 
+    # The Flutter web client is served from this same port so that it loads and
+    # opens its websocket on one origin. Without that the client cannot reach
+    # /ws at all.
+    def web_client_root
+      return @web_client_root if defined?(@web_client_root)
+
+      configured = ENV["RUFLET_WEB_CLIENT_DIR"].to_s.strip
+      @web_client_root =
+        if configured.empty? || !File.directory?(configured)
+          nil
+        else
+          File.expand_path(configured)
+        end
+    end
+
+    def serve_web_client(socket, request_path)
+      root = web_client_root
+      return false unless root
+
+      relative = request_path
+      relative = "/index.html" if relative.empty? || relative == "/"
+      candidate = File.expand_path(File.join(root, relative))
+      # Never serve outside the client bundle.
+      return false unless candidate == root || candidate.start_with?("#{root}#{File::SEPARATOR}")
+      return false unless File.file?(candidate)
+
+      content = read_binary_file(candidate)
+      write_http_response(socket, 200, content_type_for(candidate), content, binary: true)
+      true
+    end
+
     def serve_asset(socket, path)
       asset_path = resolve_asset_path(path)
       unless asset_path
@@ -392,6 +458,28 @@ module Ruflet
         "image/webp"
       when ".svg"
         "image/svg+xml"
+      when ".html", ".htm"
+        "text/html; charset=utf-8"
+      when ".js", ".mjs"
+        "text/javascript; charset=utf-8"
+      when ".css"
+        "text/css; charset=utf-8"
+      when ".json", ".map"
+        "application/json; charset=utf-8"
+      when ".wasm"
+        "application/wasm"
+      when ".ttf"
+        "font/ttf"
+      when ".otf"
+        "font/otf"
+      when ".woff"
+        "font/woff"
+      when ".woff2"
+        "font/woff2"
+      when ".ico"
+        "image/x-icon"
+      when ".txt", ".symbols"
+        "text/plain; charset=utf-8"
       else
         "application/octet-stream"
       end
@@ -533,11 +621,23 @@ module Ruflet
       normalized = Protocol.normalize_register_payload(payload)
       session_id = normalized["session_id"].to_s.empty? ? pseudo_uuid : normalized["session_id"]
 
+      # Run the app block BEFORE responding and ship the complete state in the
+      # register response (page_patch), like Flet. The client merges that map
+      # by control id, keeping existing instances alive — required for
+      # reconnecting clients (backend restarts) whose control store persists.
+      # Incremental op patches sent during the block are superseded by the
+      # full state and dropped; everything else is flushed afterwards.
+      registered = false
+      buffered = []
       page = Page.new(
         session_id: session_id,
         client_details: normalized,
         sender: lambda do |action, msg_payload|
-          send_message(ws, action, msg_payload)
+          if registered
+            send_message(ws, action, msg_payload)
+          else
+            buffered << [action, msg_payload]
+          end
         end
       )
 
@@ -547,14 +647,29 @@ module Ruflet
         @sessions[ws.session_key] = page
       end
 
+      @app_block.call(page)
+
+      page_patch = page.respond_to?(:register_page_patch) ? page.register_page_patch : {}
+      response = begin
+        Protocol.register_response(session_id: session_id, page_patch: page_patch)
+      rescue ArgumentError
+        # Older ruflet_core without the page_patch parameter.
+        page_patch = {}
+        Protocol.register_response(session_id: session_id)
+      end
       initial_response = [
         Protocol::ACTIONS[:register_client],
-        Protocol.register_response(session_id: session_id)
+        response
       ]
       ws.send_binary(Ruflet::WireCodec.pack(initial_response))
+      registered = true
 
-      @app_block.call(page)
-      page.update
+      buffered.each do |action, msg_payload|
+        next if action == Protocol::ACTIONS[:patch_control]
+
+        send_message(ws, action, msg_payload)
+      end
+      page.update if page_patch.empty?
     rescue StandardError => e
       send_message(ws, Protocol::ACTIONS[:session_crashed], { "message" => e.message })
       raise e

data/lib/ruflet/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Ruflet
-  VERSION = "0.0.18" unless const_defined?(:VERSION)
+  VERSION = "0.0.20" unless const_defined?(:VERSION)
 end

data/lib/ruflet_server.rb

@@ -2,18 +2,4 @@
 
 require "ruflet_core"
 require_relative "ruflet/server"
-
-module Ruflet
-  module_function
-
-  def run(entrypoint = nil, host: "0.0.0.0", port: nil, &block)
-    callback = entrypoint || block
-    raise ArgumentError, "Ruflet.run requires a callable entrypoint or block" unless callback.respond_to?(:call)
-    port = resolved_run_port(port) if respond_to?(:resolved_run_port)
-    port = 8550 if port.nil?
-
-    Server.new(host: host, port: port) do |page|
-      callback.call(page)
-    end.start
-  end
-end
+require_relative "ruflet/server/connection_protocol"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruflet_server
 version: !ruby/object:Gem::Version
-  version: 0.0.18
+  version: 0.0.20
 platform: ruby
 authors:
 - AdamMusa
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.0.18
+        version: 0.0.20
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.0.18
+        version: 0.0.20
 description: Ruflet WebSocket server runtime compatible with Flet protocol.
 email:
 - adammusa2222@gmail.com
@@ -32,6 +32,7 @@ extra_rdoc_files: []
 files:
 - README.md
 - lib/ruflet/server.rb
+- lib/ruflet/server/connection_protocol.rb
 - lib/ruflet/server/web_socket_connection.rb
 - lib/ruflet/server/wire_codec.rb
 - lib/ruflet/version.rb