onetimer 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1d4fcc9a49372780a20e6759680cecd890a0120515c50c2120a1161fbe96b448
+  data.tar.gz: c2506fb1a9033af810c3413958abe80b35f093690a5fc2feee69bb13b2ea1505
+SHA512:
+  metadata.gz: dc3bbd42e86ed66d44d8596fb590fbea6b610abec00a69dcf382f217e3c4dccd55be269fac89e4d62505ae885436749df5d4545226fe342853583fbb2366d314
+  data.tar.gz: 329e21f3b88544e2f397061340e6568d3385719248146f1fa8d1bfe25b2468b47bb3f7ec6d86c99d5242ea909ed03f5981d30ee0a4b5c0a71ef6fb5851583cd5

data/.github/workflows/ci.yml

@@ -0,0 +1,17 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.2"
+          bundler-cache: true
+      - run: bundle exec rake

data/.github/workflows/publish.yml

@@ -0,0 +1,26 @@
+name: Publish to RubyGems
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.2"
+          bundler-cache: true
+      - run: bundle exec rake test rubocop
+      - name: Build and push gem
+        env:
+          GEM_HOST_API_KEY: ${{ secrets.RUBYGEMS_API_KEY }}
+        run: |
+          mkdir -p pkg
+          gem build onetimer.gemspec -o pkg/onetimer.gem
+          gem push pkg/onetimer.gem

data/README.md

@@ -0,0 +1,80 @@
+# Onetimer
+
+Runs one-off data tasks exactly once, the way `db:migrate` runs schema
+migrations exactly once — safe to run repeatedly, safe across concurrent
+deploy machines.
+
+## Installation
+
+```ruby
+gem "onetimer"
+```
+
+```bash
+bundle install
+bin/rails generate onetimer:install
+bin/rails db:migrate
+```
+
+The generator adds a migration for the `onetimer_tasks` tracking table and
+creates `lib/one_timers/`.
+
+## Usage
+
+Generate a task:
+
+```bash
+bin/rake onetimer:new NAME=backfill_something
+```
+
+This creates `lib/one_timers/<timestamp>_backfill_something.rb`:
+
+```ruby
+module OneTimers
+  class BackfillSomething
+    def run
+      # One-time task logic goes here.
+    end
+  end
+end
+```
+
+Run pending tasks (idempotent — already-completed tasks are skipped):
+
+```bash
+bin/rake onetimer:run
+```
+
+Typically wired into your deploy entrypoint alongside `db:migrate`.
+
+## Configuration
+
+Tasks live in `lib/one_timers/` by default. Override in an initializer:
+
+```ruby
+Rails.application.config.onetimer.tasks_dir = Rails.root.join("lib/data_tasks")
+```
+
+## Development
+
+```bash
+just setup
+just test
+just lint
+```
+
+## Releasing
+
+1. Bump `Onetimer::VERSION` in `lib/onetimer/version.rb`, commit.
+2. `just release` — tags the commit and pushes the tag.
+3. CI (`.github/workflows/publish.yml`) builds the gem and pushes it to
+   RubyGems.org using the `RUBYGEMS_API_KEY` repo secret.
+
+One-time setup: add a RubyGems.org API key (Account → API Keys, scoped to
+"Push rubygem") as the `RUBYGEMS_API_KEY` secret in the repo's Actions
+settings.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/z19r/onetimer.

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/app/models/onetimer/task.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Onetimer
+  class Task < ApplicationRecord
+    self.table_name = "onetimer_tasks"
+
+    validates :name, presence: true, uniqueness: true
+    validates :status, inclusion: { in: %w[running completed] }
+  end
+end

data/justfile

@@ -0,0 +1,38 @@
+## Onetimer — development workflows
+
+# First-time setup: install dependencies
+setup:
+    bundle install
+
+# Run the test suite
+test:
+    bundle exec rake test
+
+# Run RuboCop
+lint:
+    bundle exec rubocop
+
+# Auto-fix RuboCop offenses where safe
+lint-fix:
+    bundle exec rubocop -a
+
+# Run tests + lint (mirrors the default rake task)
+build:
+    bundle exec rake
+
+# Open an interactive console with the gem loaded
+console:
+    bin/console
+
+# Remove generated test artifacts
+clean:
+    rm -rf test/dummy/db/*.sqlite3 test/dummy/log coverage pkg
+
+# Tag the version in lib/onetimer/version.rb and push — CI publishes to RubyGems
+release:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    version=$(ruby -Ilib -e 'require "onetimer/version"; puts Onetimer::VERSION')
+    git tag "v${version}"
+    git push origin "v${version}"
+    echo "Pushed v${version} — CI will build and publish to RubyGems"

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/migration"
+
+module Onetimer
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      def self.next_migration_number(dirname)
+        ActiveRecord::Generators::Base.next_migration_number(dirname)
+      end
+
+      def create_migration_file
+        migration_template(
+          "create_onetimer_tasks.rb.erb",
+          "db/migrate/create_onetimer_tasks.rb"
+        )
+      end
+
+      def create_tasks_directory
+        empty_directory "lib/one_timers"
+        create_file "lib/one_timers/.keep"
+      end
+
+      private
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
+      end
+    end
+  end
+end

data/lib/generators/onetimer/install/templates/create_onetimer_tasks.rb.erb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+class CreateOnetimerTasks < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :onetimer_tasks do |t|
+      t.string :name, null: false
+      t.string :status, null: false, default: "running"
+      t.datetime :started_at, null: false
+      t.datetime :finished_at
+
+      t.timestamps
+    end
+
+    add_index :onetimer_tasks, :name, unique: true
+  end
+end

data/lib/onetimer/engine.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Onetimer
+  class Engine < ::Rails::Engine
+    isolate_namespace Onetimer
+
+    config.onetimer = ActiveSupport::OrderedOptions.new
+    config.onetimer.tasks_dir = nil # set per-host-app; defaults to Rails.root/lib/one_timers
+
+    initializer "onetimer.tasks_dir" do |app|
+      Onetimer.tasks_dir = app.config.onetimer.tasks_dir || Rails.root.join("lib/one_timers")
+    end
+
+    rake_tasks do
+      load File.expand_path("../tasks/onetimer.rake", __dir__)
+    end
+  end
+end

data/lib/onetimer/runner.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Onetimer
+  # Runs one-off data tasks exactly once, the way db:migrate runs schema
+  # migrations exactly once. Task files live in Onetimer.tasks_dir (default
+  # lib/one_timers/), named <timestamp>_<description>.rb, each defining
+  # OneTimers::<Description> with a #run method. Generate one with
+  # `rake onetimer:new NAME=...`.
+  class Runner
+    def self.run_pending!
+      task_files.each { |file| run_task(file) }
+    end
+
+    def self.generate!(name)
+      timestamp = Time.current.strftime("%Y%m%d%H%M%S")
+      class_name = name.camelize
+      path = Onetimer.tasks_dir.join("#{timestamp}_#{name.underscore}.rb")
+
+      FileUtils.mkdir_p(Onetimer.tasks_dir)
+      File.write(path, <<~RUBY)
+        # frozen_string_literal: true
+
+        module OneTimers
+          class #{class_name}
+            def run
+              # One-time task logic goes here.
+            end
+          end
+        end
+      RUBY
+
+      path
+    end
+
+    def self.task_files
+      Dir.glob(Onetimer.tasks_dir.join("*.rb")).sort
+    end
+    private_class_method :task_files
+
+    def self.run_task(file)
+      name = File.basename(file, ".rb")
+      return if Task.exists?(name: name, status: "completed")
+
+      task = claim(name)
+      return unless task # already completed or claimed by another process
+
+      require file
+      class_for(file).new.run
+      task.update!(status: "completed", finished_at: Time.current)
+      Rails.logger.info "[Onetimer] completed #{name}"
+    rescue StandardError => e
+      task&.destroy!
+      Rails.logger.error "[Onetimer] failed #{name}: #{e.message}"
+      raise
+    end
+    private_class_method :run_task
+
+    # Unique index on name makes this an atomic claim: if two processes
+    # (e.g. concurrent deploy machines) race to run the same task, only
+    # one succeeds in creating the row and actually runs it.
+    def self.claim(name)
+      Task.create!(name: name, status: "running", started_at: Time.current)
+    rescue ActiveRecord::RecordInvalid, ActiveRecord::RecordNotUnique
+      nil
+    end
+    private_class_method :claim
+
+    def self.class_for(file)
+      class_name = File.basename(file, ".rb").sub(/\A\d+_/, "").camelize
+      "OneTimers::#{class_name}".constantize
+    end
+    private_class_method :class_for
+  end
+end

data/lib/onetimer/version.rb

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

data/lib/onetimer.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "onetimer/version"
+require "onetimer/engine"
+require "onetimer/runner"
+
+module Onetimer
+  class Error < StandardError; end
+
+  class << self
+    attr_accessor :tasks_dir
+  end
+end

data/lib/tasks/onetimer.rake

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+namespace :onetimer do
+  desc "Run any pending one-off tasks (idempotent, safe to run repeatedly)"
+  task run: :environment do
+    Onetimer::Runner.run_pending!
+  end
+
+  desc "Generate a new one-off task, e.g. rake onetimer:new NAME=backfill_x"
+  task new: :environment do
+    name = ENV.fetch("NAME") { abort "Usage: rake onetimer:new NAME=backfill_x" }
+    path = Onetimer::Runner.generate!(name)
+    puts "Created #{path}"
+  end
+end

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification
+name: onetimer
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Zack Kitzmiller
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-08-30 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  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 tiny Rails engine that gives you a lib/one_timers/ directory of run-once
+  data tasks, tracked in the database so each one runs exactly once across any number
+  of deploy machines.
+email:
+- zackkitzmiller@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/ci.yml"
+- ".github/workflows/publish.yml"
+- README.md
+- Rakefile
+- app/models/onetimer/task.rb
+- justfile
+- lib/generators/onetimer/install/install_generator.rb
+- lib/generators/onetimer/install/templates/create_onetimer_tasks.rb.erb
+- lib/onetimer.rb
+- lib/onetimer/engine.rb
+- lib/onetimer/runner.rb
+- lib/onetimer/version.rb
+- lib/tasks/onetimer.rake
+homepage: https://github.com/z19r/onetimer
+licenses:
+- Nonstandard
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/z19r/onetimer
+  source_code_uri: https://github.com/z19r/onetimer
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Runs one-off data tasks exactly once, the way db:migrate runs schema migrations.
+test_files: []