duoruby 0.1.0

data/lib/duoruby/cli.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require "duoruby/version"
+
+module DuoRuby
+  # Command-line interface for the +duoruby+ executable.
+  #
+  # Commands:
+  # - +help+    — prints usage information
+  # - +version+ — prints the gem version
+  # - +serve+   — starts the HTTP/WebSocket server (accepts +--host+ and +--port+ options)
+  # - +launch+  — starts the server and opens a native webview window
+  #
+  # All commands return an integer exit code. +duoruby/server+ is required lazily
+  # by +serve+ to avoid loading Falcon/Async for other commands.
+  #
+  # @example Programmatic use (mirrors the +exe/duoruby+ entry point)
+  #   exit DuoRuby::CLI.new(ARGV, input: $stdin, output: $stdout).call
+  class CLI
+    # @param args [Array<String>] the command-line arguments (typically +ARGV+)
+    # @param input [IO] standard input (reserved for future interactive use)
+    # @param output [IO] standard output where all messages are printed
+    def initialize(args, input:, output:)
+      @args = args
+      @input = input
+      @output = output
+    end
+
+    # Dispatches to the appropriate command handler.
+    #
+    # @return [Integer] 0 on success, 1 on error
+    def call
+      case @args.first
+      when nil, "help", "--help", "-h"
+        help
+      when "version", "--version", "-v"
+        @output.puts VERSION
+        0
+      when "serve"
+        serve
+      when "launch"
+        launch
+      else
+        @output.puts "unknown command: #{@args.first}"
+        1
+      end
+    end
+
+    private
+
+    # Prints usage summary.
+    # @return [Integer] 0
+    def help
+      @output.puts "duoruby help"
+      @output.puts "duoruby version"
+      @output.puts "duoruby serve [--host HOST] [--port PORT]"
+      @output.puts "duoruby launch [--host HOST] [--port PORT] [--title TITLE]"
+      0
+    end
+
+    # Parses +--host+ and +--port+ options, then starts the server.
+    #
+    # @return [Integer] 0 on success, 1 on option parse failure
+    def serve
+      options = serve_options
+      return 1 unless options
+
+      require "duoruby/server"
+
+      DuoRuby::Server.build(**options).run(output: @output)
+      0
+    end
+
+    # Parses options and opens a native webview window backed by the server.
+    #
+    # @return [Integer] 0 on success, 1 on option parse failure
+    def launch
+      options = launch_options
+      return 1 unless options
+
+      require "duoruby/launcher"
+
+      DuoRuby::Launcher.new(**options).run(output: @output)
+      0
+    end
+
+    # Parses the options that follow the +launch+ command.
+    #
+    # @return [Hash, nil]
+    def launch_options
+      options = {root: Dir.pwd}
+      args = @args.drop(1)
+
+      until args.empty?
+        case (arg = args.shift)
+        when "--host"
+          return missing_option_value if args.empty?
+
+          options[:host] = args.shift
+        when "--port"
+          return missing_option_value if args.empty?
+
+          options[:port] = parse_port(args.shift)
+          return unless options[:port]
+        when "--title"
+          return missing_option_value if args.empty?
+
+          options[:title] = args.shift
+        else
+          @output.puts "unknown launch option: #{arg}"
+          return
+        end
+      end
+
+      options
+    end
+
+    # Parses the options that follow the +serve+ command.
+    #
+    # @return [Hash, nil] option hash on success, +nil+ on parse failure
+    def serve_options
+      options = {root: Dir.pwd}
+      args = @args.drop(1)
+
+      until args.empty?
+        case (arg = args.shift)
+        when "--host"
+          return missing_option_value if args.empty?
+
+          options[:host] = args.shift
+        when "--port"
+          return missing_option_value if args.empty?
+
+          options[:port] = parse_port(args.shift)
+          return unless options[:port]
+        else
+          @output.puts "unknown serve option: #{arg}"
+          return
+        end
+      end
+
+      options
+    end
+
+    # Prints a "missing value" error and returns +nil+.
+    def missing_option_value
+      @output.puts "missing option value"
+      nil
+    end
+
+    # Parses +value+ as a TCP port number (1–65535).
+    # Prints an error and returns +nil+ for anything invalid.
+    #
+    # @param value [String] the raw port string
+    # @return [Integer, nil]
+    def parse_port(value)
+      port = Integer(value)
+      return port if port.between?(1, 65_535)
+    rescue ArgumentError, TypeError
+      nil
+    ensure
+      @output.puts "invalid serve port: #{value}" unless port&.between?(1, 65_535)
+    end
+  end
+end

data/lib/duoruby/client.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require "duoruby/message"
+require "duoruby/reply_promise"
+require "duoruby/channel/namespace"
+
+module DuoRuby
+  # Represents a single connected WebSocket client.
+  #
+  # Client wraps the low-level connection writer and acts as a typed
+  # key-value store for per-connection application state (e.g. current
+  # room, display name, authentication status).
+  #
+  # Instances are created by {Server#connect} and passed as the first
+  # argument to every server event handler.
+  #
+  # @example Sending a message to a client
+  #   client.send(:snapshot, rooms: ["lobby"], users: ["Alice"])
+  #
+  # @example Storing and reading application state
+  #   client[:name] = "Alice"
+  #   client[:name]  # => "Alice"
+  class Client
+    # @return [String] the unique connection identifier assigned by the server
+    attr_reader :id
+
+    # @return [Hash{Symbol => Object}] per-client application state
+    attr_reader :attributes
+
+    # @return [Hash{Symbol => Group}] groups this client currently belongs to
+    attr_reader :groups
+
+    attr_reader :metadata
+
+    # @param id [String] a unique identifier for this connection
+    # @param writer [Proc, nil] callable that accepts a serialized message Hash;
+    #   mutually exclusive with the block form
+    # @yieldparam message [Hash] the serialized message to deliver
+    def initialize(id:, writer: nil, metadata: {}, &writer_block)
+      @id = id
+      @writer = writer || writer_block
+      @metadata = metadata
+      @attributes = {}
+      @groups = {}
+      @accepted = true
+      @pending_calls = {}
+      @next_call_id = 0
+    end
+
+    # Reads an application attribute by symbol key.
+    # @param key [String, Symbol]
+    # @return [Object, nil]
+    def [](key)
+      attributes[key.to_sym]
+    end
+
+    # Writes an application attribute. Keys are always stored as symbols.
+    # @param key [String, Symbol]
+    # @param value [Object]
+    def []=(key, value)
+      attributes[key.to_sym] = value
+    end
+
+    # Sends a message to this client over the WebSocket connection.
+    #
+    # @param event [String, Symbol] the event name
+    # @param params keyword arguments that become the message params
+    def send(event, **params)
+      return send_question(event, **params) if question_event?(event)
+
+      @writer.call(Message.new(event, **params).to_h)
+    end
+
+    def deliver(message)
+      @writer.call(Message.coerce(message).to_h)
+    end
+
+    def channel(name)
+      Channel::Namespace.new(self, name)
+    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
+
+    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 join(group)
+      group.add(self)
+    end
+
+    def leave(group)
+      group.remove(self)
+    end
+
+    def accepted?
+      @accepted
+    end
+
+    def reject(code: :unauthorized, message: "connection rejected", details: nil)
+      @accepted = false
+      cancel_pending_calls(code: code, message: message, details: details)
+      deliver(Message.error(code: code, message: message, details: details))
+      self
+    end
+
+    private
+
+    def question_event?(event)
+      event.to_s.end_with?("?")
+    end
+
+    def send_question(event, **params)
+      id = next_call_id
+      promise = ReplyPromise.new
+      @pending_calls[id] = promise
+      @writer.call(Message.request(event, id, **params).to_h)
+      promise
+    end
+
+    def next_call_id
+      @next_call_id += 1
+      "call-#{@next_call_id}"
+    end
+  end
+end

data/lib/duoruby/config.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module DuoRuby
+  # Holds framework-level configuration set by the application's +duoruby.rb+.
+  #
+  # @example In <root>/duoruby.rb
+  #   DuoRuby.configure do |c|
+  #     c.title = "My App"
+  #   end
+  class Config
+    # @return [String] the window title used by +duoruby launch+
+    attr_accessor :title
+
+    # @return [String, nil] the server host, set by the framework before loading the app
+    attr_accessor :host
+
+    # @return [Integer, nil] the server port, set by the framework before loading the app
+    attr_accessor :port
+
+    # @return [Array<String>] extra gems whose Opal sources are added to the frontend build
+    attr_accessor :frontend_gems
+
+    # @return [Array<String>] paths to stub (compile as empty) in the frontend Opal build
+    attr_accessor :frontend_stubs
+
+    def initialize
+      @title = "DuoRuby"
+      @frontend_gems = []
+      @frontend_stubs = []
+    end
+  end
+
+  # Returns the current framework configuration object.
+  # @return [Config]
+  def self.config
+    @config ||= Config.new
+  end
+
+  # Yields the configuration object for mutation.
+  #
+  # @yieldparam config [Config]
+  def self.configure
+    yield config
+  end
+end

data/lib/duoruby/group.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require "duoruby/channel/namespace"
+
+module DuoRuby
+  # A named set of clients that can be messaged as a unit.
+  #
+  # Groups provide the broadcast primitive for server-side pub/sub. Membership
+  # is bidirectional: the group tracks its members, and each {Client} tracks
+  # which groups it belongs to. This makes it cheap to remove a client from
+  # all its groups on disconnect without iterating every group.
+  #
+  # Groups are created lazily by {Server#group} and are keyed by symbol name.
+  #
+  # @example Adding a client to a group and broadcasting
+  #   server.group(:lobby) << client
+  #   server.group(:lobby).send(:announcement, text: "Server restart in 5 min")
+  class Group
+    class Selection
+      def initialize(members)
+        @members = members
+      end
+
+      def send(event, **params)
+        replies = @members.map { |client| client.send(event, **params) }
+        return replies if question_event?(event)
+
+        self
+      end
+
+      def channel(name)
+        Channel::Namespace.new(self, name)
+      end
+
+      private
+
+      def question_event?(event)
+        event.to_s.end_with?("?")
+      end
+    end
+
+    # @return [Symbol] the group's name
+    attr_reader :name
+
+    # @return [Array<Client>] current members, in the order they joined
+    attr_reader :members
+
+    # @param name [String, Symbol] the group name; stored as a Symbol
+    def initialize(name)
+      @name = name.to_sym
+      @members = []
+    end
+
+    # Adds +client+ to the group (no-op if already a member).
+    # Also registers this group in +client.groups+.
+    #
+    # @param client [Client]
+    # @return [self]
+    def add(client)
+      members << client unless members.include?(client)
+      client.groups[name] = self
+      self
+    end
+
+    # Shovel operator — same as {#add}.
+    alias << add
+
+    # Removes +client+ from the group and unregisters the group from +client.groups+.
+    #
+    # @param client [Client]
+    # @return [Client] the removed client
+    def remove(client)
+      members.delete(client)
+      client.groups.delete(name)
+      client
+    end
+
+    def include?(client)
+      members.include?(client)
+    end
+
+    def size
+      members.size
+    end
+
+    def empty?
+      members.empty?
+    end
+
+    def except(*clients)
+      Selection.new(members - clients)
+    end
+
+    def send_to_others(client, event, **params)
+      except(client).send(event, **params)
+      self
+    end
+
+    def channel(name)
+      Channel::Namespace.new(self, name)
+    end
+
+    # Sends +event+ with +params+ to every current member.
+    #
+    # @param event [String, Symbol] the event name
+    # @param params keyword arguments forwarded to each {Client#send}
+    # @return [self]
+    def send(event, **params)
+      replies = members.map { |client| client.send(event, **params) }
+      return replies if question_event?(event)
+
+      self
+    end
+
+    private
+
+    def question_event?(event)
+      event.to_s.end_with?("?")
+    end
+  end
+end

data/lib/duoruby/launcher.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "socket"
+require "duoruby/config"
+require "webview_util"
+
+module DuoRuby
+  # Starts the server in a child process and opens a native webview window
+  # on the main process's main thread.
+  #
+  # GTK requires all calls on the thread that called gtk_init (the OS main
+  # thread). The Async/Falcon server runs in a forked child process so each
+  # has full ownership of its own event loop. When the window is closed the
+  # child is terminated; when the child dies unexpectedly the window closes.
+  #
+  # The window title defaults to +DuoRuby.config.title+, which the application
+  # can set in its +duoruby.rb+ config file:
+  #
+  #   DuoRuby.configure { |c| c.title = "My App" }
+  #
+  # @example
+  #   DuoRuby::Launcher.new(root: __dir__).run
+  class Launcher
+    # @param root   [String]       application root directory
+    # @param host   [String]       server host (default: +"127.0.0.1"+)
+    # @param port   [Integer, nil] server port; +nil+ picks a free port automatically
+    # @param title  [String, nil]  window title; +nil+ uses +DuoRuby.config.title+
+    # @param width  [Integer]      window width in pixels (default: +1280+)
+    # @param height [Integer]      window height in pixels (default: +800+)
+    def initialize(root: Dir.pwd, host: "127.0.0.1", port: nil,
+                   title: nil, width: 1280, height: 800)
+      @root   = File.expand_path(root)
+      @host   = host
+      @port   = port || free_port
+      @title  = title
+      @width  = width
+      @height = height
+    end
+
+    # Forks the Async server into a child process, then opens the native
+    # window on the main thread. Blocks until the window is closed, then
+    # terminates the server child.
+    #
+    # @param output [IO] where to print the launch banner (default: +$stdout+)
+    def run(output: $stdout)
+      output.puts "launching http://#{@host}:#{@port}"
+
+      server_pid = fork { run_server }
+
+      wait_for_server
+
+      title = @title || DuoRuby.config.title
+      window = WebviewUtil::Window.new(title: title, width: @width, height: @height)
+      window.navigate("http://#{@host}:#{@port}")
+      window.run
+    ensure
+      if server_pid
+        Process.kill(:TERM, server_pid) rescue nil
+        Process.waitpid(server_pid) rescue nil
+      end
+    end
+
+    private
+
+    # Runs the server in the child process.
+    def run_server
+      require "console"
+      require "duoruby/server"
+      Console.logger.fatal!
+      Server.build(root: @root, host: @host, port: @port)
+            .run(output: File.open(File::NULL, "w"))
+    end
+
+    # Allocates a free TCP port by binding to port 0 and reading the assigned port.
+    def free_port
+      server = TCPServer.new(@host, 0)
+      server.addr[1]
+    ensure
+      server&.close
+    end
+
+    # Polls until the server is accepting TCP connections.
+    def wait_for_server
+      loop do
+        TCPSocket.new(@host, @port).close
+        break
+      rescue Errno::ECONNREFUSED
+        sleep 0.05
+      end
+    end
+  end
+end

data/lib/duoruby/message.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "duoruby/version"
+
+module DuoRuby
+  # Represents a single WebSocket message: an event name and a keyword params hash.
+  #
+  # Messages are the protocol unit shared between backend and frontend. They
+  # serialize to a plain Hash for JSON transport and can be coerced back from
+  # that same Hash (with either string or symbol keys).
+  #
+  # @example Creating a message
+  #   msg = Message.new("chat", text: "hello")
+  #   msg.event   # => "chat"
+  #   msg.params  # => {text: "hello"}
+  #   msg.to_h    # => {"event" => "chat", "params" => {"text" => "hello"}}
+  #
+  # @example Coercing from a parsed JSON hash
+  #   Message.coerce("event" => "chat", "params" => {"text" => "hello"})
+  class Message
+    REPLY_EVENT = "$reply"
+    ERROR_EVENT = "$error"
+
+    attr_reader :event, :params, :id, :reply_to
+
+    def self.request(event, request_id, **params)
+      new(event, params, id: request_id)
+    end
+
+    def self.reply(reply_to, result)
+      new(REPLY_EVENT, {result: result}, reply_to: reply_to)
+    end
+
+    def self.error(code:, message:, details: nil, reply_to: nil)
+      params = {code: code.to_s, message: message.to_s}
+      params[:details] = details if details
+      new(ERROR_EVENT, params, reply_to: reply_to)
+    end
+
+    # Coerces +value+ into a Message.
+    #
+    # If +value+ is already a Message it is returned unchanged.
+    # Otherwise +value+ is treated as a Hash with string or symbol keys
+    # containing an +event+ key and an optional +params+ key.
+    #
+    # @param value [Message, Hash] the value to coerce
+    # @return [Message]
+    def self.coerce(value)
+      return value if value.is_a?(Message)
+
+      params = value.fetch("params") { value.fetch(:params, {}) }
+      new(
+        value.fetch("event") { value.fetch(:event) },
+        params.transform_keys(&:to_sym),
+        id: value.fetch("id") { value.fetch(:id, nil) },
+        reply_to: value.fetch("reply_to") { value.fetch(:reply_to, nil) }
+      )
+    end
+
+    # @param event [String, Symbol] the event name; stored as a String
+    # @param params [Hash] keyword params accompanying the event
+    def initialize(event, params = nil, id: nil, reply_to: nil, **keyword_params)
+      @event = event.to_s
+      @params = params || keyword_params
+      @id = id
+      @reply_to = reply_to
+    end
+
+    # Serializes the message to a plain Hash suitable for JSON encoding.
+    # Both the +event+ key and all +params+ keys are strings.
+    #
+    # @return [Hash]
+    def to_h
+      {"event" => event, "params" => params.transform_keys(&:to_s)}.tap do |message|
+        message["id"] = id if id
+        message["reply_to"] = reply_to if reply_to
+      end
+    end
+  end
+end

data/lib/duoruby/reply_error.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module DuoRuby
+  class ReplyError < StandardError
+    attr_reader :code, :details, :params
+
+    def initialize(params)
+      @params = params.transform_keys(&:to_sym)
+      @code = @params[:code].to_s
+      @details = @params[:details]
+      super(@params[:message].to_s)
+    end
+  end
+end