wallflower 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ba9a1d426696f5a091d18e4266c1ef2e5dfcb8166e110b3e143e3417fa055af7
+  data.tar.gz: '09abd80d4d1f08ec0a38bbe7ef19b5ae75601631da08edc3125cb6027a987097'
+SHA512:
+  metadata.gz: dc04356f627dcee3e1181778f479a49762ef5b72444238df923dbb37e8a71f710d1327eeffc0020fbe84e447c08088baac6e0c3b2e8f8b995ee147b1ab26035b
+  data.tar.gz: 8e98021b01854edc0548b4f8f73eaff8759c97bd572bfadf951d685cc169fe3d7cfbfe71bb441619d68da7a7e03e55ac3a3311c39386a632f43b6a48d180875d

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2026 Tyler Schneider
+
+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,80 @@
+# Wallflower
+
+Background task tracking for Rails apps: a person starts long-running work, follows its status and progress, and gets its result when it finishes.
+
+## Installation
+
+Add the gem and run its install generator, which copies a migration for its tasks table:
+
+```ruby
+gem "wallflower"
+```
+
+```bash
+bundle install
+bin/rails generate wallflower:install
+bin/rails db:migrate
+```
+
+Mount the engine at the path its pages should live under:
+
+```ruby
+mount Wallflower::Engine => "/background"
+```
+
+## Configuration
+
+Every setting has a default, so set only what differs in your app:
+
+```ruby
+Wallflower.configure do |config|
+  config.authentication_method = :authenticate_user! # runs before every Wallflower page
+  config.current_person_method = :current_user       # returns the person who starts and views tasks
+  config.current_account_method = nil                # returns the account a task belongs to, when there is one
+  config.layout = "application"                      # the layout Wallflower's pages are drawn in
+end
+```
+
+## Kinds and runners
+
+A kind is a type of task the app offers, such as an export. Register each one in an initializer with its key, its title and the name of its runner class:
+
+```ruby
+Wallflower.register_kind :export_transactions, title: "Export transactions", runner: "ExportTransactionsRunner"
+```
+
+An app whose registered runner class does not exist fails to boot, with a message naming the class.
+
+A runner is a plain class whose `call` receives the task. The task carries the `params`, `person` and `account` it was started with, and the runner reports progress on it while it works:
+
+```ruby
+class ExportTransactionsRunner
+  def call(task)
+    rows = Transaction.where(month: task.params["month"])
+    task.set_total(rows.count)
+    rows.find_each { |row| export(row); task.advance }
+  end
+end
+```
+
+A runner that produces a file attaches it as the task's result:
+
+```ruby
+task.attach_result(io: StringIO.new(csv), filename: "transactions.csv")
+```
+
+A finished task's page then offers a Download button. The file is sent through Wallflower's own route, which gives it only to the person who started the task and answers anyone else with not found.
+
+## Starting a task
+
+```ruby
+task = Wallflower.start(kind: :export_transactions, person: current_user, account: current_account, params: { "month" => "2026-10" })
+```
+
+The task is returned queued and its job is enqueued. When the job runs, the task is marked running, its runner is called, and when the runner returns the task is marked finished with the time it finished.
+
+## The task page
+
+A task's page lives at `tasks/:id` under the engine's mount path. The person who started the task sees its kind's title, its status and, once the runner has set a total, a progress bar of done against total. The page listens for changes to its task over Turbo Streams, so its status and progress update without a reload, in a browser and in the Hotwire Native iOS app alike. Anyone else, and the same person viewing from another account, gets a not-found response.
+
+Wallflower's pages are drawn with keystone_ui, and live updates need Action Cable and turbo-rails, which the host's layout already loads for Turbo Streams.

data/Rakefile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task default: :test

data/app/controllers/wallflower/application_controller.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Wallflower
+  class ApplicationController < ::ApplicationController
+    before_action { send(Wallflower.configuration.authentication_method) }
+
+    layout -> { Wallflower.configuration.layout }
+
+    helper KeystoneUiHelper
+
+    private
+
+    def wallflower_person
+      send(Wallflower.configuration.current_person_method)
+    end
+
+    def wallflower_account
+      send(Wallflower.configuration.current_account_method)
+    end
+  end
+end

data/app/controllers/wallflower/tasks_controller.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Wallflower
+  class TasksController < ApplicationController
+    def index
+    end
+
+    def show
+      @task = visible_tasks.find_by(id: params[:id])
+      head :not_found unless @task
+    end
+
+    def download
+      task = visible_tasks.find_by(id: params[:id])
+      return head :not_found unless task&.result_file&.attached?
+
+      send_data task.result_file.download, filename: task.result_file.filename.to_s, type: task.result_file.content_type
+    end
+
+    private
+
+    def visible_tasks
+      tasks = Task.where(person: wallflower_person)
+      Wallflower.configuration.current_account_method ? tasks.where(account: wallflower_account) : tasks
+    end
+  end
+end

data/app/jobs/wallflower/run_job.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Wallflower
+  class RunJob < ActiveJob::Base
+    def perform(task)
+      task.update!(status: "running")
+      Wallflower.kind(task.kind).runner.constantize.new.call(task)
+      task.update!(status: "finished", finished_at: Time.current)
+    end
+  end
+end

data/app/models/wallflower/application_record.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Wallflower
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/wallflower/task.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Wallflower
+  class Task < ApplicationRecord
+    self.table_name = "wallflower_tasks"
+
+    belongs_to :person, polymorphic: true
+    belongs_to :account, polymorphic: true, optional: true
+
+    has_one_attached :result_file
+
+    after_update_commit do
+      broadcast_replace_to self, target: ActionView::RecordIdentifier.dom_id(self, :live), partial: "wallflower/tasks/live", locals: { task: self }
+    end
+
+    def kind_title
+      Wallflower.kind(kind).title
+    end
+
+    def attach_result(io:, filename:)
+      result_file.attach(io: io, filename: filename)
+    end
+
+    def set_total(total)
+      update!(total: total)
+    end
+
+    def advance(by = 1)
+      increment(:done, by).save!
+    end
+  end
+end

data/app/views/wallflower/tasks/_live.html.erb

@@ -0,0 +1,8 @@
+<div id="<%= dom_id(task, :live) %>">
+  <p id="<%= dom_id(task, :status) %>"><%= task.status.humanize %></p>
+  <div id="<%= dom_id(task, :progress) %>">
+    <% if task.total %>
+      <%= render Keystone::Ui::ProgressComponent.new(value: task.done, max: task.total, label: "#{task.done} of #{task.total}") %>
+    <% end %>
+  </div>
+</div>

data/app/views/wallflower/tasks/index.html.erb

@@ -0,0 +1 @@
+<h1>Tasks</h1>

data/app/views/wallflower/tasks/show.html.erb

@@ -0,0 +1,8 @@
+<%= turbo_stream_from @task %>
+<%= ui_page(max_width: :md) do %>
+  <h1><%= @task.kind_title %></h1>
+  <%= render "wallflower/tasks/live", task: @task %>
+  <% if @task.status == "finished" && @task.result_file.attached? %>
+    <%= ui_button(label: "Download", href: download_task_path(@task), variant: :secondary) %>
+  <% end %>
+<% end %>

data/config/routes.rb

@@ -0,0 +1,6 @@
+Wallflower::Engine.routes.draw do
+  root "tasks#index"
+  resources :tasks, only: :show do
+    get :download, on: :member
+  end
+end

data/lib/generators/wallflower/install/install_generator.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Wallflower
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Installs Wallflower: copies its migration."
+
+      def copy_migration
+        migration_template "create_wallflower_tasks.rb.erb", "db/migrate/create_wallflower_tasks.rb"
+      end
+    end
+  end
+end

data/lib/generators/wallflower/install/templates/create_wallflower_tasks.rb.erb

@@ -0,0 +1,15 @@
+class CreateWallflowerTasks < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :wallflower_tasks do |t|
+      t.string :kind, null: false
+      t.string :status, null: false, default: "queued"
+      t.json :params, null: false, default: {}
+      t.integer :total
+      t.integer :done, null: false, default: 0
+      t.datetime :finished_at
+      t.references :person, polymorphic: true, null: false
+      t.references :account, polymorphic: true, null: true
+      t.timestamps
+    end
+  end
+end

data/lib/wallflower/configuration.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Wallflower
+  class Configuration
+    attr_accessor :authentication_method, :layout, :current_person_method, :current_account_method
+
+    def initialize
+      @authentication_method = :authenticate_user!
+      @layout = "application"
+      @current_person_method = :current_user
+    end
+  end
+
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  def self.configure
+    yield(configuration)
+  end
+
+  def self.reset_configuration!
+    @configuration = Configuration.new
+  end
+end

data/lib/wallflower/engine.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Wallflower
+  class Engine < ::Rails::Engine
+    isolate_namespace Wallflower
+
+    config.after_initialize { Wallflower.check_kinds! }
+  end
+end

data/lib/wallflower/kinds.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Wallflower
+  Kind = Struct.new(:key, :title, :runner, keyword_init: true)
+
+  class MissingRunner < StandardError; end
+
+  def self.register_kind(key, title:, runner:)
+    kinds[key.to_sym] = Kind.new(key: key.to_sym, title: title, runner: runner.to_s)
+  end
+
+  def self.kind(key)
+    kinds.fetch(key.to_sym)
+  end
+
+  def self.kinds
+    @kinds ||= {}
+  end
+
+  def self.check_kinds!
+    kinds.each_value do |kind|
+      next if kind.runner.safe_constantize
+
+      raise MissingRunner, "Wallflower kind #{kind.key} names the runner #{kind.runner}, which does not exist."
+    end
+  end
+
+  def self.reset_kinds!
+    @kinds = {}
+  end
+end

data/lib/wallflower/version.rb

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

data/lib/wallflower.rb

@@ -0,0 +1,12 @@
+require "keystone_ui"
+require "turbo-rails"
+require "wallflower/version"
+require "wallflower/configuration"
+require "wallflower/kinds"
+require "wallflower/engine"
+
+module Wallflower
+  def self.start(kind:, person:, account: nil, params: {})
+    Task.create!(kind: kind.to_s, person: person, account: account, params: params).tap { |task| RunJob.perform_later(task) }
+  end
+end

metadata

@@ -0,0 +1,136 @@
+--- !ruby/object:Gem::Specification
+name: wallflower
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Tyler Schneider
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: keystone_ui
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.37.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.37.0
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: turbo-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+description: A Rails engine that lets a person start long-running work, follow its
+  status and progress, and get its result when it finishes.
+email:
+- tylercschneider@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/controllers/wallflower/application_controller.rb
+- app/controllers/wallflower/tasks_controller.rb
+- app/jobs/wallflower/run_job.rb
+- app/models/wallflower/application_record.rb
+- app/models/wallflower/task.rb
+- app/views/wallflower/tasks/_live.html.erb
+- app/views/wallflower/tasks/index.html.erb
+- app/views/wallflower/tasks/show.html.erb
+- config/routes.rb
+- lib/generators/wallflower/install/install_generator.rb
+- lib/generators/wallflower/install/templates/create_wallflower_tasks.rb.erb
+- lib/wallflower.rb
+- lib/wallflower/configuration.rb
+- lib/wallflower/engine.rb
+- lib/wallflower/kinds.rb
+- lib/wallflower/version.rb
+homepage: https://github.com/DYB-Development/wallflower
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/DYB-Development/wallflower
+  source_code_uri: https://github.com/DYB-Development/wallflower
+  changelog_uri: https://github.com/DYB-Development/wallflower/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/DYB-Development/wallflower/issues
+  documentation_uri: https://github.com/DYB-Development/wallflower#readme
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Background task tracking for Rails apps.
+test_files: []