duoruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6f3074e802c24846379df300d0012092cd00a18513fe87bf1a62d757bb0d1fe4
+  data.tar.gz: 3603e0dbc7808566d8cec775a0513068438fe9456fd322aa6f53ca534d5c0142
+SHA512:
+  metadata.gz: f0cad5cb7f45d9801398bb6d3e2f945f35e3178407ebcf6a781aab081ca0d5b73ede700ce27ab656005b935e11c8ba782b130dc08eb7578daf0278bf1b2218f9
+  data.tar.gz: b5e8e428393c969a3aaf2e161ab0307efc965364230de19fb095c4cf93ba92adff574b2b861bdceaec1cd6d4326245b26e2d0ea83848635e7e87bd994f606638

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DuoRuby contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,169 @@
+# DuoRuby
+
+DuoRuby is a lightweight Ruby framework for WebSocket-first applications with a CRuby server and an Opal browser socket.
+
+It gives Ruby applications a compact message DSL that works on both sides of the connection: browser sockets, server-side clients, and groups all use `send :event, **params`, while handlers use `on :event` with keyword parameters.
+
+The main use case is building web-based desktop applications: run Ruby on the local machine, write the frontend in Ruby through Opal, open it with `duoruby launch`, and still keep the same app loadable remotely through `duoruby serve`.
+
+The API and CLI are still evolving and should be considered unstable until version 1.0.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "duoruby"
+```
+
+And then execute:
+
+```sh
+bundle install
+```
+
+For local development from this checkout:
+
+```sh
+bundle install
+bundle exec rake
+bundle exec rake opal_spec
+```
+
+## How It Works
+
+DuoRuby is organized around one server object and one browser socket object:
+
+- `DuoRuby::Server` owns HTTP serving, WebSocket upgrades, connected clients, groups, authentication hooks, and message handlers.
+- `DuoRuby::Socket` runs in the browser through Opal and owns the client-side WebSocket transport.
+- `require "duoruby"` loads the server setup on CRuby and the browser setup on Opal.
+- Application boot files live at `app/setup/backend.rb` and `app/setup/frontend.rb`.
+- `duoruby serve` starts the Falcon-backed development server, serves `/`, compiles Opal frontend code to `/duoruby/app.js`, and bridges `/duoruby/socket` to the server.
+- `duoruby launch` starts the same server and opens it in a native webview window for a desktop-app feel.
+- Because launched apps are still served over HTTP/WebSocket, the same project can also be loaded from another browser when you expose the host/port intentionally.
+
+Rack is not part of the default boot path.
+
+## Quick Start
+
+Server-side application code:
+
+```ruby
+class Chat::Server < DuoRuby::Server
+  on :join do |client, name:|
+    client[:name] = name
+    group(:lobby) << client
+    group(:lobby).send(:joined, name: name)
+  end
+
+  on :message do |client, text:|
+    group(:lobby).send(:message, name: client[:name], text: text)
+  end
+
+  on :name? do |client|
+    client[:name]
+  end
+end
+```
+
+Browser-side application code:
+
+```ruby
+class Chat::Socket < DuoRuby::Socket
+  on :joined do |name:|
+    puts "#{name} joined"
+  end
+
+  on :message do |name:, text:|
+    puts "#{name}: #{text}"
+  end
+end
+
+socket = Chat::Socket.new
+socket.connect
+socket.send(:join, name: "Ada")
+```
+
+Events ending in `?` are request/reply questions. They return a promise that can be awaited:
+
+```ruby
+# await: true
+
+name = socket.send(:name?).__await__
+```
+
+Handlers reply to questions by returning a value. If a handler raises, DuoRuby sends a structured error reply.
+
+## Examples
+
+Run the chat example:
+
+```sh
+cd examples/chat
+bundle install
+bundle exec duoruby serve
+```
+
+Open `http://127.0.0.1:9292` in two browser windows. The sample app supports named rooms, presence lists, recent room history, room switching, leave, and validation errors.
+
+To open it in a native webview window instead:
+
+```sh
+bundle exec duoruby launch
+```
+
+Run the Glimmer counter example:
+
+```sh
+cd examples/glimmer_counter
+bundle install
+bundle exec duoruby serve
+```
+
+Run the Ready Room game example:
+
+```sh
+cd examples/ready_room
+bundle install
+bundle exec duoruby serve
+```
+
+Ready Room demonstrates namespaced game events, browser-to-server questions, server-to-browser questions, group question collections, structured reply errors, and reconnect state sync.
+
+## API
+
+- `DuoRuby::Server#on(event, &block)` registers server-side message handlers.
+- `DuoRuby::Server#group(name)` returns a broadcast group.
+- `DuoRuby::Server#broadcast(event, **params)` sends an event to all connected clients.
+- `DuoRuby::Client#channel(name)` and `DuoRuby::Group#channel(name)` send namespaced events without spelling raw colon-prefixed event names.
+- `DuoRuby::Socket#connect` opens the default `/duoruby/socket` transport.
+- `DuoRuby::Socket#send(event, **params)` sends fire-and-forget events or promise-returning `?` questions.
+- `DuoRuby::Client#send(event, **params)` sends from the server to a browser socket with the same `?` question convention.
+- `DuoRuby::Testing.connect` wires a server and socket together in memory for specs.
+- `duoruby launch [--host HOST] [--port PORT] [--title TITLE]` runs the app server and opens a native webview window.
+
+Lifecycle events use `$`-prefixed names:
+
+- `:$connect`
+- `:$disconnect`
+- `:$reconnect`
+
+## Development
+
+Run from the repository root:
+
+```sh
+bundle install
+bundle exec rake
+bundle exec rake opal_spec
+```
+
+The default Rake task runs the CRuby RSpec suite. `bundle exec rake opal_spec` runs the Opal browser-side specs.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/rbutils/duoruby.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE.txt).

data/exe/duoruby

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "duoruby/setup/backend"
+require "duoruby/cli"
+
+exit DuoRuby::CLI.new(ARGV, input: $stdin, output: $stdout).call

data/lib/duoruby/boot.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "duoruby/config"
+
+module DuoRuby
+  # Application bootstrapping helpers.
+  #
+  # These methods locate and load the two conventional application files for a
+  # given side (+:backend+ or +:frontend+):
+  #
+  #   <root>/duoruby.rb               # optional shared config
+  #   <root>/app/setup/<side>.rb      # side-specific entry point
+  #
+  # They also ensure the application's root and +app/+ directories are on
+  # +$LOAD_PATH+ so application code can +require+ its own files without
+  # specifying full paths.
+
+  # Loads the application files for +side+ from +root+, adding the root and
+  # +app/+ directories to +$LOAD_PATH+ first.
+  #
+  # Uses +Kernel#load+ for both files so they are always re-evaluated (rather
+  # than skipped if previously required). Both files are optional — only those
+  # that exist are loaded.
+  #
+  # @param side [:backend, :frontend] which side to boot
+  # @param root [String] the application root directory (defaults to +Dir.pwd+)
+  # @return [Array<String>] absolute paths of the files that were loaded
+  def self.boot(side = :backend, root: Dir.pwd)
+    root = prepare_root(root)
+    paths = app_paths(side, root: root)
+
+    paths = paths.select { |path| File.file?(path) }
+    paths.each { |path| load path }
+    paths
+  end
+
+  # Loads the application files for +side+ and returns the registered app object.
+  #
+  # This is a CRuby/server-side method — it is never run inside an Opal
+  # compiled bundle. Both files are loaded with +Kernel#load+ (a runtime file
+  # loader that accepts a computed path) rather than +require+.
+  #
+  # The setup file is expected to call +DuoRuby.app = <instance>+ to register
+  # the backend it creates. {.load_app} returns that registered value and clears
+  # the slot so successive calls in the same process behave independently.
+  #
+  # @param side [:backend, :frontend] which side to load
+  # @param root [String] the application root directory
+  # @return [Object, nil] the value passed to +DuoRuby.app=+, or +nil+ if the
+  #   setup file does not exist or no app was registered
+  def self.load_app(side = :backend, root: Dir.pwd)
+    root = prepare_root(root)
+    config_path = File.join(root, "duoruby.rb")
+    load config_path if File.file?(config_path)
+
+    setup_path = File.join(root, "app", "setup", "#{side}.rb")
+    return unless File.file?(setup_path)
+
+    load setup_path
+    @app.tap { @app = nil }
+  end
+
+  # Registers the application instance produced by a setup file.
+  # Called from within +app/setup/<side>.rb+; the registered value is read
+  # back by {.load_app} and then cleared.
+  #
+  # @param instance [Object] the backend or frontend instance
+  def self.app=(instance)
+    @app = instance
+  end
+
+  # Expands +root+ to an absolute path and prepends both +<root>+ and
+  # +<root>/app+ to +$LOAD_PATH+ (unless already present).
+  #
+  # @param root [String] the raw root path
+  # @return [String] the expanded absolute root path
+  def self.prepare_root(root)
+    root = File.expand_path(root)
+    [File.join(root, "app"), root].each do |path|
+      $LOAD_PATH.unshift(path) unless $LOAD_PATH.include?(path)
+    end
+
+    root
+  end
+
+  # Returns the canonical pair of application file paths for +side+.
+  #
+  # @param side [:backend, :frontend]
+  # @param root [String] the application root directory
+  # @return [Array<String, String>] +[config_path, setup_path]+
+  def self.app_paths(side, root: Dir.pwd)
+    root = File.expand_path(root)
+    [File.join(root, "duoruby.rb"), File.join(root, "app", "setup", "#{side}.rb")]
+  end
+end

data/lib/duoruby/channel/handler_methods.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module DuoRuby
+  class Channel
+    module HandlerMethods
+      def self.included(receiver)
+        receiver.extend(self)
+      end
+
+      def handlers
+        @handlers ||= {}
+      end
+
+      def on(event, &handler)
+        add_handler(event, false, &handler)
+      end
+
+      def one(event, &handler)
+        add_handler(event, true, &handler)
+      end
+
+      def off(event = nil, handler = nil, &block)
+        remove_handler(handlers, event, handler || block)
+      end
+
+      def channel(name)
+        Namespace.new(self, name)
+      end
+
+      def included(receiver)
+        receiver.__send__(:merge_handlers, handlers)
+        super if defined?(super)
+      end
+
+      protected
+
+      def add_handler(event, once, &handler)
+        raise ArgumentError, "handler required" unless handler
+
+        event = normalize_event(event)
+        handlers[event] ||= []
+        Handler.new(event, handler, once).tap { |registered| handlers[event] << registered }
+      end
+
+      def merge_handlers(other_handlers)
+        @handlers = clone_handlers(handlers)
+        other_handlers.each do |event, event_handlers|
+          @handlers[event] ||= []
+          @handlers[event].concat(event_handlers.map { |h| Handler.new(h.event, h.block, h.once) })
+        end
+      end
+
+      def clone_handlers(source)
+        source.each_with_object({}) do |(event, event_handlers), cloned|
+          cloned[event] = event_handlers.map { |h| Handler.new(h.event, h.block, h.once) }
+        end
+      end
+
+      def normalize_event(event)
+        event.to_s
+      end
+
+      def remove_handler(source, event = nil, handler = nil)
+        return source.clear unless event
+
+        if event.is_a?(Handler)
+          source[event.event]&.delete_if { |registered| same_handler?(registered, event) }
+          source.delete(event.event) if source[event.event]&.empty?
+          return
+        end
+
+        event = normalize_event(event)
+        return source.delete(event) unless handler
+
+        source[event]&.delete_if { |registered| same_handler?(registered, handler) }
+        source.delete(event) if source[event]&.empty?
+      end
+
+      def same_handler?(registered, handler)
+        return registered.equal?(handler) || registered.block.equal?(handler.block) if handler.is_a?(Handler)
+
+        registered.block.equal?(handler)
+      end
+    end
+  end
+end

data/lib/duoruby/channel/namespace.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module DuoRuby
+  class Channel
+    class Namespace
+      def initialize(target, name)
+        @target = target
+        @name = name.to_s
+      end
+
+      def on(event, &handler)
+        @target.on(namespaced(event), &handler)
+      end
+
+      def one(event, &handler)
+        @target.one(namespaced(event), &handler)
+      end
+
+      def off(event = nil, handler = nil, &block)
+        return @target.off unless event
+
+        @target.off(namespaced(event), handler, &block)
+      end
+
+      def trigger(event, *args, **params)
+        @target.trigger(namespaced(event), *args, **params)
+      end
+
+      def send(event, **params)
+        @target.send(namespaced(event), **params)
+      end
+
+      private
+
+      def namespaced(event)
+        "#{@name}:#{event}"
+      end
+    end
+  end
+end

data/lib/duoruby/channel.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require "duoruby/channel/namespace"
+require "duoruby/channel/handler_methods"
+
+module DuoRuby
+  # Base class for event-driven components in DuoRuby.
+  #
+  # Channel provides a flexible pub/sub event system with support for:
+  # - Class-level handler declarations that are inherited by subclasses
+  # - Module-level handler declarations that merge into including classes
+  # - Per-instance handler isolation (class handlers are deep-cloned on initialize)
+  # - One-shot handlers via {#one}
+  # - Wildcard handlers that run on every event via {#on} with the +*+ event name
+  # - Removal by event name, proc reference, or Handler token
+  #
+  # {Server} and {Socket} both inherit from Channel.
+  #
+  # @example Declaring handlers at the class level (inherited by instances)
+  #   class MyServer < DuoRuby::Server
+  #     on(:join) { |client, room:| group(room) << client }
+  #   end
+  #
+  # @example Adding handlers on an instance
+  #   server = MyServer.new
+  #   token = server.on(:join) { |client, room:| puts "#{client.id} joined #{room}" }
+  #   server.off(token)  # remove by token
+  class Channel
+    # @return [Hash{String => Array<Handler>}] the event-to-handlers map for this object
+    attr_reader :handlers
+
+    # Internal record tying a block to its event and once-flag.
+    # The value returned by {#on} and {#one} is a Handler; pass it to {#off}
+    # to remove that specific registration.
+    Handler = Struct.new(:event, :block, :once)
+
+    extend HandlerMethods
+
+    # Copies the parent class's handlers into the subclass when a subclass is defined.
+    # @private
+    def self.inherited(subclass)
+      subclass.__send__(:merge_handlers, handlers)
+      super
+    end
+
+    # Deep-clones the class-level handlers into this instance so that instance-level
+    # {#on}/{#off} calls do not affect the class or other instances.
+    def initialize
+      @handlers = self.class.__send__(:clone_handlers, self.class.handlers)
+    end
+
+    # Registers a persistent instance-level handler for +event+.
+    # Instance handlers stack on top of any class-level handlers that were
+    # copied in at initialize time.
+    #
+    # @param event [String, Symbol] event name; use +"*"+ to match every event
+    # @return [Handler] removal token
+    def on(event, &handler)
+      raise ArgumentError, "handler required" unless handler
+
+      event = event.to_s
+      handlers[event] ||= []
+      Handler.new(event, handler, false).tap { |registered| handlers[event] << registered }
+    end
+
+    # Registers a one-shot instance-level handler for +event+.
+    # Automatically removed after the first dispatch.
+    #
+    # @param event [String, Symbol] event name
+    # @return [Handler] removal token
+    def one(event, &handler)
+      raise ArgumentError, "handler required" unless handler
+
+      event = event.to_s
+      handlers[event] ||= []
+      Handler.new(event, handler, true).tap { |registered| handlers[event] << registered }
+    end
+
+    # Removes instance-level handlers. See {HandlerMethods#off} for the full
+    # removal semantics — behaviour is identical at the instance level.
+    def off(event = nil, handler = nil, &block)
+      target = handler || block
+      return handlers.clear unless event
+
+      if event.is_a?(Handler)
+        handlers[event.event]&.delete_if { |r| handler_identity?(r, event) }
+        handlers.delete(event.event) if handlers[event.event]&.empty?
+        return
+      end
+
+      event = event.to_s
+      return handlers.delete(event) unless target
+
+      handlers[event]&.delete_if { |r| handler_identity?(r, target) }
+      handlers.delete(event) if handlers[event]&.empty?
+    end
+
+    def channel(name)
+      Namespace.new(self, name)
+    end
+
+    # Returns a Proc wrapping the first registered handler for +event+, bound
+    # to this instance via +instance_exec+. Returns +nil+ if no handler exists.
+    # Used internally; may be useful for adapter integrations.
+    #
+    # @param event [String, Symbol]
+    # @return [Proc, nil]
+    def handler_for(event)
+      event = event.to_s
+      handler = handlers[event]&.first
+      proc { |*args, **params| instance_exec(*args, **params, &handler.block) } if handler
+    end
+
+    # Dispatches +event+ to all registered handlers, then to any wildcard (+*+) handlers.
+    #
+    # All handlers are invoked via +instance_exec+ so they run in the context of
+    # this Channel instance. Positional +args+ and keyword +params+ are forwarded
+    # as-is. One-shot handlers are removed immediately after firing.
+    #
+    # @param event [String, Symbol] the event name
+    # @param args positional arguments to forward (e.g. the client in Server handlers)
+    # @param params keyword arguments to forward (e.g. message params)
+    # @return [nil]
+    def dispatch(event, *args, **params)
+      event = event.to_s
+      results = dispatch_handlers(event, handlers[event], *args, **params)
+      dispatch_handlers("*", handlers["*"], event, *args, **params)
+      results
+    end
+
+    # Alias for {#dispatch}.
+    alias trigger dispatch
+
+    private
+
+    # Checks handler identity by object identity (for Handler tokens) or
+    # block proc identity (for raw Proc arguments).
+    def handler_identity?(registered, handler)
+      return registered.equal?(handler) || registered.block.equal?(handler.block) if handler.is_a?(Handler)
+
+      registered.block.equal?(handler)
+    end
+
+    # Iterates over a snapshot of +event_handlers+, invoking each via +instance_exec+.
+    # Removes one-shot handlers after they fire.
+    def dispatch_handlers(event, event_handlers, *args, **params)
+      return [] unless event_handlers
+
+      event_handlers.dup.map do |handler|
+        result = instance_exec(*args, **params, &handler.block)
+        off(event, handler.block) if handler.once
+        result
+      end
+    end
+  end
+end