duoruby 0.1.0

data/lib/duoruby/reply_promise.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "async"
+require "async/promise"
+require "duoruby/reply_error"
+
+module DuoRuby
+  # Async-backed server-side reply promise.
+  #
+  # It keeps Async::Promise's native #wait API and adds the small PromiseV2-like
+  # surface DuoRuby exposes across runtimes.
+  class ReplyPromise < Async::Promise
+    def await(...)
+      wait(...)
+    end
+
+    alias_method :__await__, :await
+
+    def then(&handler)
+      return self unless handler
+
+      if resolved?
+        handler.call(wait) if completed?
+      else
+        schedule { call_success(handler) }
+      end
+
+      self
+    end
+
+    def fail(&handler)
+      return self unless handler
+
+      if resolved?
+        call_failure(handler)
+      else
+        schedule { call_failure(handler) }
+      end
+
+      self
+    end
+
+    alias_method :rescue, :fail
+
+    private
+
+    def call_failure(handler)
+      wait
+    rescue StandardError => error
+      handler.call(error)
+    end
+
+    def call_success(handler)
+      handler.call(wait)
+    rescue StandardError
+      nil
+    end
+
+    def schedule(&block)
+      if (task = Async::Task.current?)
+        task.async(&block)
+      else
+        Thread.new(&block)
+      end
+    end
+  end
+end

data/lib/duoruby/server/frontend_compiler.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "opal"
+require "opal/builder"
+require "opal-browser"
+require "duoruby/config"
+
+module DuoRuby
+  class Server
+    class FrontendCompiler
+      def initialize(root)
+        @root = root
+      end
+
+      def call
+        Opal.reset_paths!
+        Opal.use_gem("opal-browser")
+        Opal.use_gem("paggio")
+        Opal.append_path(File.join(Gem::Specification.find_by_name("opal-browser").gem_dir, "opal"))
+        append_frontend_gems
+
+        builder = Opal::Builder.new
+        builder.stubs.concat(DuoRuby.config.frontend_stubs)
+        builder.append_paths(File.join(@root, "app"), File.expand_path("../..", __dir__))
+        builder.build("opal")
+        builder.build("setup/frontend")
+        builder.to_s
+      end
+
+      private
+
+      def append_frontend_gems
+        DuoRuby.config.frontend_gems.each do |gem_name|
+          Opal.use_gem(gem_name)
+          spec = Gem::Specification.find_by_name(gem_name)
+          opal_dir = File.join(spec.gem_dir, "opal")
+          Opal.append_path(opal_dir) if File.directory?(opal_dir)
+        end
+      end
+    end
+  end
+end

data/lib/duoruby/server.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+require "async"
+require "async/http/endpoint"
+require "async/websocket/adapters/http"
+require "falcon/server"
+require "protocol/http/response"
+require "duoruby/boot"
+require "duoruby/message"
+require "duoruby/channel"
+require "duoruby/client"
+require "duoruby/group"
+
+module DuoRuby
+  # Application server built on Falcon and Async.
+  #
+  # Server handles three HTTP routes:
+  # - +GET /+               — serves an HTML shell page that loads the frontend script
+  # - +GET /duoruby/app.js+ — compiles and serves the Opal frontend on demand
+  # - +GET /duoruby/socket+ — upgrades to a WebSocket and drives message handlers
+  #
+  # Subclasses can declare message handlers with +on+ and can override +#call+ for
+  # custom HTTP routes before delegating to +super+.
+  #
+  # @example Starting the server from application code
+  #   DuoRuby::Server.build(root: __dir__, port: 3000).run
+  class Server < Channel
+    require "duoruby/server/frontend_compiler"
+
+    # Path that the browser WebSocket connects to.
+    SOCKET_PATH = "/duoruby/socket"
+
+    # Path from which the compiled frontend JavaScript is served.
+    SCRIPT_PATH = "/duoruby/app.js"
+
+    # @return [String] the expanded application root directory
+    attr_reader :root
+
+    # @return [String] the bind host
+    attr_reader :host
+
+    # @return [Integer] the bind port
+    attr_reader :port
+
+    # @return [Hash{Symbol => Group}] all groups that have been accessed on this server
+    attr_reader :groups
+
+    # @param root [String] the application root directory
+    # @param host [String] the hostname or IP to bind to (default: +"127.0.0.1"+)
+    # @param port [Integer, String] the port to listen on (default: +9292+)
+    def initialize(root: Dir.pwd, host: "127.0.0.1", port: 9292)
+      super()
+      configure(root: root, host: host, port: port)
+      @groups = {}
+      @next_client_id = 0
+    end
+
+    def self.build(root: Dir.pwd, host: "127.0.0.1", port: 9292)
+      root = File.expand_path(root)
+      server = DuoRuby.load_app(:backend, root: root) || new(root: root, host: host, port: port)
+      server.configure(root: root, host: host, port: port)
+      server
+    end
+
+    def configure(root:, host:, port:)
+      @root = File.expand_path(root)
+      config_path = File.join(@root, "duoruby.rb")
+      load config_path if File.file?(config_path)
+      @host = host
+      @port = Integer(port)
+      DuoRuby.config.host = @host
+      DuoRuby.config.port = @port
+      self
+    end
+
+    # Rack-compatible request handler. Routes to the appropriate private handler
+    # or returns a 404. Catches +StandardError+ and responds with a 500.
+    #
+    # @param request [Protocol::HTTP::Request]
+    # @return [Protocol::HTTP::Response]
+    def call(request)
+      path = request.path.to_s.split("?", 2).first
+
+      case path
+      when SOCKET_PATH
+        websocket(request) || not_found("websocket endpoint")
+      when SCRIPT_PATH
+        javascript
+      when "/", ""
+        html
+      else
+        not_found(path)
+      end
+    rescue StandardError => error
+      text(500, "#{error.class}: #{error.message}\n")
+    end
+
+    # Starts the Falcon server and blocks until it exits.
+    #
+    # @param output [IO] where to print the "serving …" banner (default: +$stdout+)
+    def run(output: $stdout)
+      endpoint = Async::HTTP::Endpoint.parse("http://#{host}:#{port}")
+
+      Sync do
+        task = Falcon::Server.new(self, endpoint).run
+        output.puts "serving http://#{host}:#{port}"
+        task.wait
+      ensure
+        task&.stop
+      end
+    end
+
+    # Compiles the Opal frontend to a JavaScript string.
+    #
+    # Resets Opal's global path state, adds configured frontend gems, then
+    # builds the +opal+ runtime followed by +setup/frontend+.
+    #
+    # Note: this method mutates global Opal state (+Opal.reset_paths!+) and
+    # is not safe to call concurrently.
+    #
+    # @return [String] the concatenated JavaScript
+    def frontend_javascript
+      FrontendCompiler.new(root).call
+    end
+
+    def connect(id:, writer: nil, metadata: {}, &writer_block)
+      client = Client.new(id: id, writer: writer, metadata: metadata, &writer_block)
+      return client.reject unless authenticate(client)
+
+      dispatch(:$connect, client)
+      client
+    end
+
+    def authenticate(_client)
+      true
+    end
+
+    def disconnect(client)
+      dispatch(:$disconnect, client)
+      client.cancel_pending_calls
+      client.groups.values.each { |group| group.remove(client) }
+      client
+    end
+
+    def group(name)
+      groups[name.to_sym] ||= Group.new(name)
+    end
+
+    def broadcast(group_name, event, **params)
+      group(group_name).send(event, **params)
+    end
+
+    def receive(client, message)
+      message = Message.coerce(message)
+      return client.resolve_call(message) if message.event == Message::REPLY_EVENT
+      return client.reject_call(message) if message.event == Message::ERROR_EVENT && message.reply_to
+
+      results = dispatch(message.event, client, **message.params)
+      client.deliver(Message.reply(message.id, results.last)) if message.id
+      results
+    rescue StandardError => error
+      raise unless message&.id
+
+      client.deliver(Message.error(code: error.class.name, message: error.message, reply_to: message.id))
+    end
+
+    private
+
+    # Upgrades the request to a WebSocket, creates a Client, and loops over
+    # inbound frames until the connection closes.
+    def websocket(request)
+      Async::WebSocket::Adapters::HTTP.open(request) do |connection|
+        client = connect(id: next_client_id, metadata: connection_metadata(request)) do |message|
+          connection.send_text(JSON.generate(message))
+          connection.flush
+        end
+        return unless client.accepted?
+
+        while (text = connection.read)
+          receive(client, JSON.parse(text))
+        end
+      ensure
+        disconnect(client) if client
+      end
+    end
+
+    # Returns a new sequential client ID string.
+    def next_client_id
+      @next_client_id += 1
+      "client-#{@next_client_id}"
+    end
+
+    def connection_metadata(request)
+      query = request.path.to_s.split("?", 2)[1]
+      {
+        path: request.path.to_s.split("?", 2).first,
+        query: query ? URI.decode_www_form(query).to_h : {},
+        headers: request.headers.each.to_h
+      }
+    end
+
+    # Returns the HTML shell response.
+    def html
+      body = <<~HTML
+        <!doctype html>
+        <html>
+          <head>
+            <meta charset="utf-8">
+            <meta name="viewport" content="width=device-width, initial-scale=1">
+            <title>DuoRuby</title>
+          </head>
+          <body>
+            <div id="duoruby-root"></div>
+            <script src="#{SCRIPT_PATH}?#{Time.now.to_i}"></script>
+          </body>
+        </html>
+      HTML
+
+      response(200, body, "text/html")
+    end
+
+    # Returns the compiled JavaScript response.
+    def javascript
+      js = Thread.new { frontend_javascript }.value
+      response(200, js, "application/javascript")
+    end
+
+    # Returns a plain-text 404 response.
+    def not_found(path)
+      text(404, "not found: #{path}\n")
+    end
+
+    # Returns a plain-text response with the given status code.
+    def text(status, body)
+      response(status, body, "text/plain")
+    end
+
+    # Constructs a Protocol::HTTP::Response.
+    def response(status, body, content_type)
+      Protocol::HTTP::Response[status, {"content-type" => content_type}, [body]]
+    end
+  end
+end

data/lib/duoruby/setup/backend.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "duoruby/server"
+require "duoruby/boot"
+
+module DuoRuby
+  # Creates a new application {Server} instance, optionally configuring it via a block.
+  #
+  # The block is evaluated in the context of the server instance, so handler
+  # registration methods (+on+, +one+, +off+) are available directly.
+  #
+  # @example
+  #   server = DuoRuby.server do
+  #     on(:join) { |client, room:| group(room) << client }
+  #   end
+  #
+  # @yieldparam — (block is instance_eval'd on the server; no explicit param)
+  # @return [Server]
+  def self.server(&block)
+    Server.new.tap do |server|
+      server.instance_eval(&block) if block
+    end
+  end
+end

data/lib/duoruby/setup/frontend.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "duoruby/socket"
+
+# Load Opal/browser dependencies when running inside the compiled JavaScript bundle.
+if RUBY_ENGINE == "opal"
+  require "native"
+  require "promise/v2"
+  require "browser/setup/mini"
+  require "browser/location"
+  require "browser/socket"
+end
+
+module DuoRuby
+  # Creates a new browser {Socket} instance, optionally configuring it via a block.
+  #
+  # The block is evaluated in the context of the socket instance, so handler
+  # registration methods (+on+, +one+, +off+) are available directly.
+  #
+  # @example
+  #   socket = DuoRuby.socket do
+  #     on(:snapshot) { |rooms:, **| puts rooms.inspect }
+  #   end
+  #
+  # @param transport [Proc, nil] optional transport callable (see {Socket#initialize})
+  # @yieldparam — (block is instance_eval'd on the socket; no explicit param)
+  # @return [Socket]
+  def self.socket(transport: nil, &block)
+    Socket.new(transport: transport).tap do |socket|
+      socket.instance_eval(&block) if block
+    end
+  end
+end

data/lib/duoruby/socket/test_promise.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module DuoRuby
+  class Socket
+    class TestPromise
+      attr_reader :value, :error
+
+      def initialize
+        @resolved = false
+        @rejected = false
+        @then_handlers = []
+        @fail_handlers = []
+      end
+
+      def resolve(value = nil)
+        @resolved = true
+        @value = value
+        @then_handlers.each { |handler| handler.call(value) }
+        self
+      end
+
+      def reject(error = nil)
+        @rejected = true
+        @error = error
+        @fail_handlers.each { |handler| handler.call(error) }
+        self
+      end
+
+      def then(&handler)
+        @resolved ? handler.call(value) : @then_handlers << handler
+        self
+      end
+
+      def fail(&handler)
+        @rejected ? handler.call(error) : @fail_handlers << handler
+        self
+      end
+
+      alias_method :rescue, :fail
+    end
+  end
+end

data/lib/duoruby/socket/transport.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module DuoRuby
+  class Socket
+    module Transport
+      def self.included(receiver)
+        receiver.extend(ClassMethods)
+      end
+
+      def connect(url: nil, path: "/duoruby/socket", reconnect: false, backoff: 1)
+        raise "already connected" if @socket
+
+        @connect_url = url || self.class.default_socket_url(path)
+        @reconnect = reconnect
+        @reconnect_backoff = backoff
+        open_socket
+        self
+      end
+
+      def reconnect
+        @socket = nil
+        open_socket
+        trigger(:$reconnect)
+        self
+      end
+
+      def open_socket
+        @socket = self.class.socket_class.new(@connect_url)
+        @transport = proc { |message| socket.write(JSON.generate(message)) }
+
+        socket.on(:open) { trigger(:$connect) }
+        socket.on(:message) { |event| receive(JSON.parse(event.data)) }
+        socket.on(:close) do
+          trigger(:$disconnect)
+          cancel_pending_calls
+          schedule_reconnect if @reconnect
+        end
+      end
+
+      module ClassMethods
+        def default_socket_url(path = "/duoruby/socket")
+          raise "default socket transport is only available under Opal" unless RUBY_ENGINE == "opal"
+
+          location = $window.location
+          protocol = location.scheme == "https:" ? "wss:" : "ws:"
+          "#{protocol}//#{location.host}#{path}"
+        end
+
+        def socket_class
+          raise "default socket transport is only available under Opal" unless RUBY_ENGINE == "opal"
+
+          ::Browser::Socket
+        end
+      end
+
+      private
+
+      def schedule_reconnect
+        if RUBY_ENGINE == "opal"
+          $window.set_timeout(proc { reconnect }, @reconnect_backoff * 1000)
+        end
+      end
+    end
+  end
+end

data/lib/duoruby/socket.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require "json"
+require "duoruby/message"
+require "duoruby/channel"
+require "duoruby/reply_error"
+require "promise/v2" if RUBY_ENGINE == "opal"
+
+module DuoRuby
+  # Browser-side event hub. Manages the WebSocket connection and message dispatch.
+  #
+  # Socket inherits the full {Channel} event system. Declare handlers at the
+  # class level (inherited by subclasses) or add them at runtime on an instance.
+  #
+  # Unlike server handlers, Socket event handlers receive *only* the message
+  # params as keyword arguments — there is no client positional argument because
+  # there is exactly one connection per browser socket instance.
+  #
+  # A transport callable (proc or block) is responsible for delivering outbound
+  # messages. Under Opal it is set automatically by {#connect}; in tests you can
+  # supply any callable at construction time.
+  #
+  # @example Inline transport for testing
+  #   delivered = []
+  #   socket = DuoRuby::Socket.new { |msg| delivered << msg }
+  #   socket.send(:join, room: "lobby")
+  #
+  # @example Subclass with class-level handlers
+  #   class MySocket < DuoRuby::Socket
+  #     on(:snapshot) { |rooms:, **| puts "rooms: #{rooms.join(', ')}" }
+  #   end
+  class Socket < Channel
+    require "duoruby/socket/test_promise"
+    require "duoruby/socket/transport"
+
+    include Transport
+
+    # @return [Array<Hash>] every message sent through this socket, for inspection
+    attr_reader :sent
+
+    # @return [Browser::Socket, nil] the active WebSocket, or nil before {#connect}
+    attr_reader :socket
+
+    # @param transport [Proc, nil] callable that delivers outbound messages;
+    #   mutually exclusive with the block form. May be omitted and set later
+    #   by {#connect}.
+    # @yieldparam message [Hash] the serialized message to deliver
+    def initialize(transport: nil, &transport_block)
+      super()
+      @transport = transport || transport_block
+      @sent = []
+      @pending_calls = {}
+      @next_call_id = 0
+    end
+
+    # Sends +event+ with +params+ to the server.
+    #
+    # Events ending with +?+ are questions: they include a request id and return
+    # a promise that resolves when the server replies. Other events are
+    # fire-and-forget and return the serialized message hash.
+    #
+    # @param event [String, Symbol] the event name
+    # @param params keyword arguments that become the message params
+    # @return [Hash, PromiseV2] the serialized message or reply promise
+    def send(event, **params)
+      return send_question(event, **params) if question_event?(event)
+
+      deliver(Message.new(event, **params).to_h)
+    end
+
+    def transport=(transport)
+      @transport = transport
+    end
+
+    # Opens the WebSocket connection and wires socket lifecycle events.
+    #
+    # Only available under Opal (requires +Browser::Socket+). Raises immediately
+    # on CRuby. Raises if already connected.
+    #
+    # Sets up a JSON-serialising transport and forwards:
+    # - socket +:open+  → triggers +:$connect+
+    # - socket +:message+ → calls {#receive} with the parsed JSON payload
+    # - socket +:close+ → triggers +:$disconnect+
+    #
+    # @param url [String, nil] the full WebSocket URL; defaults to the value
+    #   returned by {.default_socket_url}
+    # @param path [String] the socket path used when +url+ is not given
+    # @return [self]
+    # @raise [RuntimeError] if called outside Opal, or if already connected
+    # Coerces +message+ and dispatches it to the appropriate event handlers.
+    # Params are forwarded as keyword arguments only (no positional client arg).
+    #
+    # @param message [Message, Hash] the inbound message (raw parsed JSON or a Message)
+    def receive(message)
+      message = Message.coerce(message)
+      return resolve_call(message) if message.event == Message::REPLY_EVENT
+      return reject_call(message) if message.event == Message::ERROR_EVENT && message.reply_to
+
+      results = dispatch(message.event, **message.params)
+      deliver(Message.reply(message.id, results.last).to_h) if message.id
+      results
+    rescue StandardError => error
+      raise unless message&.id
+
+      deliver(Message.error(code: error.class.name, message: error.message, reply_to: message.id).to_h)
+    end
+
+    def deliver(message)
+      sent << message
+      @transport.call(message) if @transport
+      message
+    end
+
+    def cancel_pending_calls(code: :disconnect, message: "connection closed", details: nil)
+      error = ReplyError.new(code: code, message: message, details: details)
+      @pending_calls.each_value { |promise| promise.reject(error) }
+      @pending_calls.clear
+      self
+    end
+
+    def self.promise_class
+      defined?(::PromiseV2) ? ::PromiseV2 : TestPromise
+    end
+
+    private
+
+    def next_call_id
+      @next_call_id += 1
+      "call-#{@next_call_id}"
+    end
+
+    def question_event?(event)
+      event.to_s.end_with?("?")
+    end
+
+    def send_question(event, **params)
+      id = next_call_id
+      promise = self.class.promise_class.new
+      @pending_calls[id] = promise
+      deliver(Message.request(event, id, **params).to_h)
+      promise
+    end
+
+    def resolve_call(message)
+      promise = @pending_calls.delete(message.reply_to)
+      promise&.resolve(message.params[:result])
+    end
+
+    def reject_call(message)
+      promise = @pending_calls.delete(message.reply_to)
+      promise&.reject(ReplyError.new(message.params))
+    end
+  end
+end

data/lib/duoruby/testing.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "duoruby/setup/backend"
+require "duoruby/setup/frontend"
+
+module DuoRuby
+  module Testing
+    Connection = Struct.new(:server, :socket, :client, keyword_init: true)
+
+    def self.connect(server: Server.new, socket: Socket.new, id: "client-1", metadata: {})
+      socket = socket.class.new if socket.is_a?(Class)
+      client = nil
+      socket_transport = proc { |message| server.receive(client, message) }
+
+      socket.transport = socket_transport
+      client = server.connect(id: id, metadata: metadata) { |message| socket.receive(message) }
+      Connection.new(server: server, socket: socket, client: client)
+    end
+  end
+end

data/lib/duoruby/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module DuoRuby
+  VERSION = "0.1.0"
+end