Module: Ruflet::Rails

Defined in:
lib/ruflet/rails.rb,
lib/ruflet/rails/assets.rb,
lib/ruflet/rails/railtie.rb,
lib/ruflet/rails/native_app.rb,
lib/ruflet/rails/route_stack.rb,
lib/ruflet/rails/webview_app.rb,
lib/ruflet/rails/form_helpers.rb,
lib/ruflet/rails/view_helpers.rb,
lib/ruflet/rails/configuration.rb,
lib/ruflet/rails/web_installer.rb,
lib/ruflet/rails/install_support.rb,
lib/ruflet/rails/protocol/runner.rb,
lib/ruflet/rails/desktop_launcher.rb,
lib/ruflet/rails/protocol/context.rb,
lib/ruflet/rails/protocol/web_app.rb,
lib/ruflet/rails/session_registry.rb,
lib/ruflet/rails/protocol/endpoint.rb,
lib/ruflet/rails/resource_component.rb,
lib/ruflet/rails/protocol/local_server.rb,
lib/ruflet/rails/protocol/mobile_loader.rb,
lib/ruflet/rails/protocol/websocket_detection.rb

Defined Under Namespace

Modules: DesktopLauncher, FormHelpers, InstallSupport, Protocol, ViewHelpers, WebInstaller Classes: Configuration, NativeApp, Railtie, ResourceComponent, RouteStack, Session, SessionRegistry

Class Method Summary collapse

Class Method Details

.app(file_path) ⇒ Object

Shorthand for a standalone app-file endpoint.

match "/ws", to: Ruflet::Rails.app(Rails.root.join("app/ruflet/main.rb")), via: :all



72
73
74
 
# File 'lib/ruflet/rails.rb', line 72

def app(file_path)
  endpoint(app_file: file_path)
end

.asset_url(source, host: nil) ⇒ Object 



43
44
45
46
47
48
49
50
51
52
 
# File 'lib/ruflet/rails/assets.rb', line 43

def asset_url(source, host: nil)
  raw = source.to_s
  return raw if absolute_url?(raw)

  path = asset_pipeline_path(raw)
  return path if absolute_url?(path)

  base = backend_url(host: host)
  base.empty? ? path : "#{base}#{path}"
end

.backend_url(host: nil) ⇒ Object

The base URL the Flutter client uses to reach this Rails app — the single source of truth for asset URLs, the build-time RUFLET_URL define and the desktop launcher. A Rails Ruflet app always needs one, so this always resolves to a usable value:

1. an explicit host: argument
2. Ruflet::Rails.config.backend_url (set it in config/initializers/ruflet.rb)
3. the host the client connected on (the live WebSocket request)

Returns “” only when none of those are available (e.g. a build with no configured backend_url) — set config.backend_url to cover that case.



37
38
39
40
41
 
# File 'lib/ruflet/rails/assets.rb', line 37

def backend_url(host: nil)
  candidate = host || config.backend_url
  candidate = request_base_url if candidate.to_s.strip.empty?
  candidate.to_s.strip.sub(%r{/+\z}, "")
end

.broadcast(&block) ⇒ Object 



39
40
41
 
# File 'lib/ruflet/rails.rb', line 39

def broadcast(&block)
  sessions.broadcast(&block)
end

.config ⇒ Object

Returns the global configuration object.



10
11
12
 
# File 'lib/ruflet/rails.rb', line 10

def config
  @config ||= Configuration.new
end

.configure {|config| ... } ⇒ Object

Yields the configuration object for block-style setup.

Ruflet::Rails.configure do |c|
  c.backend_url = "https://example.com"
end

Yields:



19
20
21
 
# File 'lib/ruflet/rails.rb', line 19

def configure
  yield config
end

.endpoint(view: nil, app_file: nil, &block) ⇒ Object

WebSocket endpoint for native mobile/desktop clients. The developer declares the entry the same way they declare a web mount — the screens the app shows live in dev code, never in framework auto-discovery:

# a standalone Ruflet app file (Ruflet.run/MyApp.new.run), per session:
match "/ws", to: Ruflet::Rails.endpoint(app_file: Rails.root.join("app/ruflet/main.rb")), via: :all

# a single component/view class (resolved lazily, so reloading works):
match "/ws", to: Ruflet::Rails.endpoint(view: "ProductComponent"), via: :all

# a custom block:
match "/ws", to: Ruflet::Rails.endpoint { |page| MyHome.render(page) }, via: :all

One of view:, app_file:, or a block is required — there is no auto-discovery fallback.

Raises:

  • (ArgumentError) 


58
59
60
61
62
63
64
65
66
67
 
# File 'lib/ruflet/rails.rb', line 58

def endpoint(view: nil, app_file: nil, &block)
  sources = [view, app_file, block].compact
  raise ArgumentError, "endpoint accepts only one of view:, app_file:, or a block" if sources.length > 1
  raise ArgumentError, "endpoint requires one of view:, app_file:, or a block" if sources.empty?

  return Protocol::Runner.new.build_app_endpoint(file_path: app_file) if app_file

  entry = block || web_app_entrypoint(view: view)
  Protocol::Runner.new(&entry).build_endpoint
end

.image_url(source, host: nil) ⇒ Object

Readability alias for image sources — identical resolution.



55
56
57
 
# File 'lib/ruflet/rails/assets.rb', line 55

def image_url(source, host: nil)
  asset_url(source, host: host)
end

.native_app(page, **opts) ⇒ Object

Start a Hotwire Native-style app. See NativeApp.



249
250
251
 
# File 'lib/ruflet/rails/native_app.rb', line 249

def native_app(page, **opts)
  NativeApp.new(page, **opts).start
end

.routed(page, &builder) ⇒ Object

Flet-style routed navigation stack for complex multi-screen apps. Wires up on_route_change / on_view_pop and starts at the current route. See Ruflet::Rails::RouteStack.

Ruflet::Rails.routed(page) do |route, nav|
  nav.push(home_view)
  nav.push(store_view) if route == "/store"
end



31
32
33
 
# File 'lib/ruflet/rails.rb', line 31

def routed(page, &builder)
  RouteStack.new(page, &builder).start
end

.sessions ⇒ Object 



35
36
37
 
# File 'lib/ruflet/rails.rb', line 35

def sessions
  @sessions ||= SessionRegistry.new
end

.view_class_for(view) ⇒ Object

Resolved lazily on each session so Rails code reloading picks up edits.



120
121
122
123
124
 
# File 'lib/ruflet/rails.rb', line 120

def view_class_for(view)
  return view if view.is_a?(Class)

  view.to_s.constantize
end

.web_app(view: nil, app_file: nil, build_dir: nil, &app_block) ⇒ Object

Self-contained web frontend, mountable under any route. Serves the Flutter web build (with <base href> rewritten to the mount point) and answers the Ruflet WebSocket on the same path. Routes stay routing-only; UI code lives in dev files:

# a single view class (resolved lazily, so reloading works):
mount Ruflet::Rails.web_app(view: "CounterView"), at: "/myfrontend"

# a standalone Ruflet app file (MyApp.new.run), loaded per session:
mount Ruflet::Rails.web_app(app_file: "app/ruflet/showcase/main.rb"), at: "/showcase"

# a custom block:
mount Ruflet::Rails.web_app { |page| MyHome.render(page) }, at: "/app"

One of view:, app_file:, or a block is required — there is no auto-discovery fallback.

Raises:

  • (ArgumentError) 


92
93
94
95
96
97
98
99
100
101
102
 
# File 'lib/ruflet/rails.rb', line 92

def web_app(view: nil, app_file: nil, build_dir: nil, &app_block)
  sources = [view, app_file, app_block].compact
  raise ArgumentError, "web_app accepts only one of view:, app_file:, or a block" if sources.length > 1
  raise ArgumentError, "web_app requires one of view:, app_file:, or a block" if sources.empty?

  Protocol::WebApp.new(
    build_dir: build_dir,
    entrypoint: web_app_entrypoint(view: view, app_file: app_file),
    &app_block
  )
end

.web_app_entrypoint(view: nil, app_file: nil) ⇒ Object 



104
105
106
107
108
109
110
111
112
113
114
115
116
117
 
# File 'lib/ruflet/rails.rb', line 104

def web_app_entrypoint(view: nil, app_file: nil)
  if view
    lambda do |page|
      view_class_for(view).render(page)
    end
  elsif app_file
    absolute = app_file.to_s
    lambda do |page, env|
      loaded = Protocol::MobileLoader.new(File.expand_path(absolute)).load!
      entry = loaded[:entrypoint]
      entry.arity == 1 ? entry.call(page) : entry.call(page, env)
    end
  end
end

.webview_app(url:, appbar: nil, navigation_bar: nil, bottom_appbar: nil, route: "/", prevent_links: nil, on_navigate: nil, on_page_started: nil, on_page_ended: nil, **webview_props) {|body| ... } ⇒ Object

Yields:

  • (body) 


33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
 
# File 'lib/ruflet/rails/webview_app.rb', line 33

def webview_app(url:, appbar: nil, navigation_bar: nil, bottom_appbar: nil,
                route: "/", prevent_links: nil, on_navigate: nil,
                on_page_started: nil, on_page_ended: nil, **webview_props)
  webview_args = { url: url, expand: true }
  webview_args[:prevent_links] = prevent_links unless prevent_links.nil?
  webview_args[:on_url_change] = ->(event) { on_navigate.call(event.data) } if on_navigate
  webview_args[:on_page_started] = on_page_started if on_page_started
  webview_args[:on_page_ended] = on_page_ended if on_page_ended
  webview_args.merge!(webview_props)

  body = Ruflet::UI::ControlFactory.build(:webview, **webview_args)
  yield body if block_given?

  view_args = { route: route, controls: [body] }
  view_args[:appbar] = appbar unless appbar.nil?
  view_args[:navigation_bar] = navigation_bar unless navigation_bar.nil?
  view_args[:bottom_appbar] = bottom_appbar unless bottom_appbar.nil?

  Ruflet::UI::ControlFactory.build(:view, **view_args)
end