tenant_kit 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: baea79f8ebb8b315e622d9689827ea30ca07aaaf8cd2469b70d251536e522d78
+  data.tar.gz: 10a2c85992094410f5528e34f85a760665ab472e36e31d9484a1c1b17d9e27c1
+SHA512:
+  metadata.gz: 2d115221d0aeb8b976ecf44b5fbb48554f9a4ed6654b515c0536058d586533824d08052419dbd56a98865b2510cd4a5b6d2457c5a5da0c9ecc5d83bb8d612469
+  data.tar.gz: 617c84f92e8475f428fe49ca7f41121e7bfb0eee030825c2641873eb75e8c91876b53aa34ea5f0d928856f3355d072b494620f3d048722bcc1b6dbe7a48fc2bc

data/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-07-01
+
+Initial release: row-level (shared-schema) multi-tenancy for Rails.
+
+### Added
+- `belongs_to_tenant` macro: declares the tenant association, scopes all reads
+  to the current tenant via `default_scope`, auto-assigns the tenant on create
+  through `before_validation`, and validates tenant presence.
+- `TenantKit::Current` (`ActiveSupport::CurrentAttributes`) as the request-scoped
+  holder of the current tenant.
+- `TenantKit.with_tenant` / `TenantKit.without_tenant` scoping controls.
+- Strict mode (`config.require_tenant`, on by default): querying a tenant-scoped
+  model with no current tenant raises `TenantKit::NoTenantSet`.
+- `validates_uniqueness_to_tenant`: uniqueness scoped to the tenant column.
+- Controller resolution helpers: `set_current_tenant_by_subdomain`,
+  `set_current_tenant_by_domain`, `set_current_tenant_by_header`, and
+  `set_current_tenant_through_filter`.
+- Background-job tenant propagation (`config.propagate_to_jobs`): the tenant's
+  GlobalID is captured at enqueue and re-established around `perform`, surviving
+  ActiveJob serialization (Solid Queue included).
+- Generators: `tenant_kit:install` and `tenant_kit:migration`.
+
+[Unreleased]: https://github.com/wintan1418/tenant_kit/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/wintan1418/tenant_kit/releases/tag/v0.1.0

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2026 wintan1418
+
+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,214 @@
+# TenantKit
+
+[![CI](https://github.com/wintan1418/tenant_kit/actions/workflows/ci.yml/badge.svg)](https://github.com/wintan1418/tenant_kit/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Row-level (shared-schema) multi-tenancy for Rails. One database, a tenant
+foreign key on every owned table, automatic query scoping, and background-job
+tenant propagation — built on `ActiveSupport::CurrentAttributes`, **strict by
+default**.
+
+## Why
+
+Most Rails SaaS apps are multi-tenant. The row-level approach — a shared schema
+with a tenant foreign key — is the simplest to operate and works cleanly with
+every Rails default (Solid Queue / Cache / Cable, standard migrations,
+connection pooling). TenantKit gives you that with safety rails:
+
+- It **refuses** to run tenant-scoped queries when no tenant is set, rather than
+  silently returning another tenant's data.
+- It **carries the current tenant into background jobs**, so async work can't
+  leak across tenants.
+- It keeps the escape hatch **loud and greppable**: `TenantKit.without_tenant`.
+
+Row-level isn't the only strategy — see [Why row-level](#why-row-level-and-not-the-others).
+
+## Requirements
+
+- Ruby `>= 3.3`
+- Rails `>= 7.2` (primary target: 8.x)
+
+## Installation
+
+```ruby
+# Gemfile
+gem "tenant_kit"
+```
+
+```bash
+bundle install
+rails g tenant_kit:install
+```
+
+The installer writes `config/initializers/tenant_kit.rb` and, unless it already
+exists, scaffolds the tenant model (`Account`) plus its migration. Pass
+`--skip-tenant-model` if you already have one.
+
+## Quick start
+
+```ruby
+# app/models/account.rb — the tenant model (does NOT call belongs_to_tenant)
+class Account < ApplicationRecord
+end
+
+# app/models/project.rb — an owned model
+class Project < ApplicationRecord
+  belongs_to_tenant
+  validates_uniqueness_to_tenant :slug
+end
+```
+
+Add the tenant column to owned tables with the migration generator:
+
+```bash
+rails g tenant_kit:migration Project
+# => db/migrate/XXXX_add_account_to_projects.rb
+#    add_reference :projects, :account, null: false, foreign_key: true, index: true
+```
+
+Resolve the tenant per request in your controller:
+
+```ruby
+# app/controllers/application_controller.rb
+class ApplicationController < ActionController::Base
+  set_current_tenant_by_subdomain(:account, :subdomain)
+end
+```
+
+Now `Project.all` returns only the current tenant's projects, and
+`Project.create!(name: "X")` auto-assigns the current tenant.
+
+## The current tenant
+
+```ruby
+TenantKit::Current.tenant            # => #<Account ...> or nil
+
+TenantKit.with_tenant(account) do
+  Project.count                      # scoped to `account`
+end
+
+TenantKit.without_tenant do
+  Project.count                      # every tenant's projects
+end
+```
+
+`with_tenant` and `without_tenant` always restore the previous state, even when
+the block raises.
+
+## Controller resolution helpers
+
+Auto-included into `ActionController::Base` and `ActionController::API`.
+
+```ruby
+set_current_tenant_by_subdomain(:account, :subdomain)  # tenant.subdomain == request.subdomain
+set_current_tenant_by_domain(:account, :domain)        # tenant.domain == request.host
+set_current_tenant_by_header("X-Tenant-Id")            # for APIs (matches tenant.id)
+
+# ...or fully custom:
+set_current_tenant_through_filter
+before_action :find_tenant
+def find_tenant
+  self.current_tenant = Account.find_by!(slug: params[:account_slug])
+end
+```
+
+`current_tenant` is also exposed as a view helper.
+
+## Background jobs
+
+When `config.propagate_to_jobs` is on (the default), every `ActiveJob` captures
+the current tenant at enqueue time and re-establishes it around `perform`. It
+works with any queue adapter — the tenant's GlobalID is folded into the job's
+serialized payload, so it survives Solid Queue too.
+
+```ruby
+TenantKit.with_tenant(account) do
+  ReportJob.perform_later          # runs later, still scoped to `account`
+end
+```
+
+Set `config.raise_on_missing_job_tenant = true` to make a job that was enqueued
+with no tenant raise at perform instead of running unscoped.
+
+## Configuration
+
+```ruby
+# config/initializers/tenant_kit.rb
+TenantKit.configure do |config|
+  config.tenant_class                = "Account"     # the tenant model
+  config.tenant_column               = "account_id"  # FK on owned tables
+  config.require_tenant              = true          # strict: raise when unscoped
+  config.propagate_to_jobs           = true          # carry tenant into ActiveJob
+  config.raise_on_missing_job_tenant = false         # job enqueued with no tenant
+end
+```
+
+## Testing
+
+```ruby
+# spec/rails_helper.rb
+require "tenant_kit/testing"
+
+RSpec.configure do |config|
+  config.include TenantKit::Testing
+  config.after { TenantKit::Current.reset }
+end
+```
+
+```ruby
+it "scopes to the tenant" do
+  as_tenant(account) do
+    expect(Project.count).to eq(0)
+  end
+end
+```
+
+## Gotchas (read this)
+
+- **`unscoped` bypasses tenant scoping.** Avoid it on tenant-owned models unless
+  you mean it. Use `without_tenant` instead — explicit and greppable.
+- **Action Cable / Turbo Streams are not auto-scoped.** Include the tenant in
+  stream names — `stream_for [current_account, record]` — so broadcasts never
+  cross tenants.
+- **Console and seeds have no request, so no current tenant.** Wrap tenant work
+  in `TenantKit.with_tenant(account) { ... }` or `TenantKit.without_tenant { }`.
+- **Unique constraints must include the tenant column** at the database level:
+  `add_index :projects, [:account_id, :slug], unique: true`. Pair it with
+  `validates_uniqueness_to_tenant :slug` in the model.
+- **Lead composite indexes with the tenant column:**
+  `add_index :projects, [:account_id, :status]`.
+
+## Why row-level (and not the others)
+
+| Strategy | Isolation | Ops cost | Verdict |
+|---|---|---|---|
+| **Row-level (shared schema)** | Good (with discipline) | Low — one DB, one migration path | **Chosen** |
+| Schema-per-tenant | Strong | High — migrations across N schemas, connection switching | Not in v1 |
+| Database-per-tenant | Strongest | Highest — provision + migrate N databases | Not in v1 |
+
+Row-level works cleanly with every Rails default and has exactly one migration
+path. With strict scoping and database constraints it is safe enough for the
+overwhelming majority of B2B SaaS.
+
+## Roadmap (not in v1)
+
+- Automatic Action Cable stream scoping
+- Solid Cache tenant-aware caching helpers
+- Schema-per-tenant / database-per-tenant modes
+
+## Development
+
+```bash
+bin/setup          # or: bundle install
+bundle exec rspec  # run the suite against spec/dummy
+bundle exec rubocop
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome at
+<https://github.com/wintan1418/tenant_kit>.
+
+## License
+
+Released under the [MIT License](MIT-LICENSE).

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/setup"
+
+require "bundler/gem_tasks"
+
+require "rspec/core/rake_task"
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

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

@@ -0,0 +1,69 @@
+require "rails/generators"
+require "rails/generators/active_record"
+
+module TenantKit
+  module Generators
+    # Installs TenantKit into a host app: writes the initializer and, unless the
+    # tenant model already exists, scaffolds it plus a migration.
+    #
+    #   rails g tenant_kit:install
+    class InstallGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      class_option :skip_tenant_model, type: :boolean, default: false,
+        desc: "Do not create the tenant model or its migration"
+
+      # Writes config/initializers/tenant_kit.rb.
+      def create_initializer
+        template "initializer.rb.tt", "config/initializers/tenant_kit.rb"
+      end
+
+      # Creates the tenant model and its migration, unless it already exists or
+      # --skip-tenant-model was passed.
+      def create_tenant_model
+        return if options[:skip_tenant_model]
+        return if tenant_model_exists?
+
+        template "tenant_model.rb.tt", "app/models/#{tenant_singular}.rb"
+        migration_template "tenant_migration.rb.tt",
+          "db/migrate/create_#{tenant_plural}.rb"
+      end
+
+      # Prints post-install guidance.
+      def show_readme
+        say ""
+        say "TenantKit installed.", :green
+        say "  1. Review config/initializers/tenant_kit.rb"
+        say "  2. Add `belongs_to_tenant` to each tenant-owned model"
+        say "  3. Add the tenant column to owned tables: rails g tenant_kit:migration Project"
+        say "  4. Resolve the tenant in ApplicationController, e.g."
+        say "       set_current_tenant_by_subdomain(:#{tenant_singular}, :subdomain)"
+        say ""
+      end
+
+      private
+
+      def tenant_class_name
+        TenantKit.config.tenant_class
+      end
+
+      def tenant_singular
+        tenant_class_name.underscore
+      end
+
+      def tenant_plural
+        tenant_singular.pluralize
+      end
+
+      def migration_version
+        "#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}"
+      end
+
+      def tenant_model_exists?
+        File.exist?(File.expand_path("app/models/#{tenant_singular}.rb", destination_root))
+      end
+    end
+  end
+end

data/lib/generators/tenant_kit/install/templates/initializer.rb.tt

@@ -0,0 +1,17 @@
+TenantKit.configure do |config|
+  # The model that represents a tenant.
+  config.tenant_class = "<%= tenant_class_name %>"
+
+  # The foreign-key column on tenant-owned tables.
+  config.tenant_column = "<%= tenant_singular %>_id"
+
+  # Strict mode: raise TenantKit::NoTenantSet when a tenant-scoped query runs
+  # with no current tenant (and not inside TenantKit.without_tenant).
+  config.require_tenant = true
+
+  # Carry the current tenant into ActiveJob background jobs.
+  config.propagate_to_jobs = true
+
+  # Raise if a job is performed with no captured tenant.
+  config.raise_on_missing_job_tenant = false
+end

data/lib/generators/tenant_kit/install/templates/tenant_migration.rb.tt

@@ -0,0 +1,14 @@
+class Create<%= tenant_plural.camelize %> < ActiveRecord::Migration[<%= migration_version %>]
+  def change
+    create_table :<%= tenant_plural %> do |t|
+      t.string :name, null: false
+      t.string :subdomain
+      t.string :domain
+
+      t.timestamps
+    end
+
+    add_index :<%= tenant_plural %>, :subdomain, unique: true
+    add_index :<%= tenant_plural %>, :domain, unique: true
+  end
+end

data/lib/generators/tenant_kit/install/templates/tenant_model.rb.tt

@@ -0,0 +1,3 @@
+class <%= tenant_class_name %> < ApplicationRecord
+  # The tenant model. It does NOT call belongs_to_tenant.
+end

data/lib/generators/tenant_kit/migration/migration_generator.rb

@@ -0,0 +1,39 @@
+require "rails/generators"
+require "rails/generators/active_record"
+
+module TenantKit
+  module Generators
+    # Generates a migration adding the tenant reference to an owned table, with a
+    # tenant-leading index and a NOT NULL foreign key.
+    #
+    #   rails g tenant_kit:migration Project
+    class MigrationGenerator < Rails::Generators::NamedBase
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      # Writes db/migrate/add_<tenant>_to_<table>.rb.
+      def create_migration_file
+        migration_template "add_tenant_reference.rb.tt",
+          "db/migrate/add_#{tenant_reference}_to_#{table_name}.rb"
+      end
+
+      private
+
+      # @return [String] pluralized, snake_case table name for the owned model.
+      def table_name
+        name.tableize
+      end
+
+      # @return [String] the tenant association name derived from the configured
+      #   tenant column (e.g. "account_id" => "account").
+      def tenant_reference
+        TenantKit.config.tenant_column.to_s.sub(/_id\z/, "")
+      end
+
+      def migration_version
+        "#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}"
+      end
+    end
+  end
+end

data/lib/generators/tenant_kit/migration/templates/add_tenant_reference.rb.tt

@@ -0,0 +1,6 @@
+class Add<%= tenant_reference.camelize %>To<%= table_name.camelize %> < ActiveRecord::Migration[<%= migration_version %>]
+  def change
+    add_reference :<%= table_name %>, :<%= tenant_reference %>,
+      null: false, foreign_key: true, index: true
+  end
+end

data/lib/tasks/tenant_kit_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :tenant_kit do
+#   # Task goes here
+# end

data/lib/tenant_kit/configuration.rb

@@ -0,0 +1,45 @@
+module TenantKit
+  # Holds the gem's configuration. Access the singleton via {TenantKit.config}
+  # and set values in +config/initializers/tenant_kit.rb+ through
+  # {TenantKit.configure}.
+  #
+  # @example
+  #   TenantKit.configure do |config|
+  #     config.tenant_class  = "Account"
+  #     config.tenant_column = "account_id"
+  #   end
+  class Configuration
+    # @return [String] name of the model that represents a tenant (e.g. "Account").
+    attr_accessor :tenant_class
+
+    # @return [String] foreign-key column on tenant-owned tables (e.g. "account_id").
+    attr_accessor :tenant_column
+
+    # @return [Boolean] strict mode: raise {NoTenantSet} when a tenant-scoped
+    #   query runs with no current tenant (and not inside +without_tenant+).
+    attr_accessor :require_tenant
+
+    # @return [Boolean] carry the current tenant into ActiveJob background jobs.
+    attr_accessor :propagate_to_jobs
+
+    # @return [Boolean] raise if a job is performed with no captured tenant
+    #   (only consulted when {#propagate_to_jobs} is true).
+    attr_accessor :raise_on_missing_job_tenant
+
+    def initialize
+      @tenant_class                = "Account"
+      @tenant_column               = "account_id"
+      @require_tenant              = true
+      @propagate_to_jobs           = true
+      @raise_on_missing_job_tenant = false
+    end
+
+    # Resolves {#tenant_class} to the actual constant, lazily so it works with
+    # Rails autoloading / reloading.
+    #
+    # @return [Class] the tenant model class.
+    def tenant_model
+      tenant_class.to_s.constantize
+    end
+  end
+end

data/lib/tenant_kit/controller_concern.rb

@@ -0,0 +1,86 @@
+module TenantKit
+  # Mixed into +ActionController::Base+ and +ActionController::API+ (via the
+  # railtie). Provides class-level helpers that install a +before_action+ to
+  # resolve and set the current tenant for each request. +CurrentAttributes+
+  # resets the tenant automatically between requests.
+  module ControllerConcern
+    extend ActiveSupport::Concern
+
+    class_methods do
+      # Resolves the tenant by request subdomain (+tenant.<field> == request.subdomain+).
+      #
+      # @param tenant_name [Symbol, nil] tenant model name (underscored). Defaults
+      #   to the configured tenant class.
+      # @param field [Symbol] the tenant column to match against. Default +:subdomain+.
+      # @return [void]
+      def set_current_tenant_by_subdomain(tenant_name = nil, field = :subdomain)
+        model = TenantKit::ControllerConcern.tenant_model_for(tenant_name)
+        before_action do
+          self.current_tenant = model.find_by(field => request.subdomain)
+        end
+      end
+
+      # Resolves the tenant by request host (+tenant.<field> == request.host+).
+      #
+      # @param tenant_name [Symbol, nil] tenant model name (underscored).
+      # @param field [Symbol] the tenant column to match against. Default +:domain+.
+      # @return [void]
+      def set_current_tenant_by_domain(tenant_name = nil, field = :domain)
+        model = TenantKit::ControllerConcern.tenant_model_for(tenant_name)
+        before_action do
+          self.current_tenant = model.find_by(field => request.host)
+        end
+      end
+
+      # Resolves the tenant by an HTTP request header — for APIs.
+      #
+      # @param header [String] the header name, e.g. +"X-Tenant-Id"+.
+      # @param tenant_name [Symbol, nil] tenant model name (underscored).
+      # @param field [Symbol] the tenant column the header value maps to. Default +:id+.
+      # @return [void]
+      def set_current_tenant_by_header(header, tenant_name = nil, field = :id)
+        model = TenantKit::ControllerConcern.tenant_model_for(tenant_name)
+        before_action do
+          value = request.headers[header]
+          self.current_tenant = value && model.find_by(field => value)
+        end
+      end
+
+      # Declares that the tenant is resolved by a custom +before_action+ the host
+      # app defines. A no-op marker for readability — assign via +current_tenant=+
+      # inside your own filter.
+      #
+      # @return [void]
+      def set_current_tenant_through_filter
+        # Intentionally empty: current_tenant= is always available.
+      end
+    end
+
+    # Resolves the tenant model class for the given (optional) name.
+    #
+    # @param tenant_name [Symbol, String, nil]
+    # @return [Class]
+    def self.tenant_model_for(tenant_name)
+      return TenantKit.config.tenant_model if tenant_name.nil?
+
+      tenant_name.to_s.camelize.constantize
+    end
+
+    included do
+      helper_method :current_tenant if respond_to?(:helper_method)
+    end
+
+    # @return [Object, nil] the current tenant for this request.
+    def current_tenant
+      TenantKit::Current.tenant
+    end
+
+    # Sets the current tenant for this request.
+    #
+    # @param tenant [Object, nil]
+    # @return [Object, nil]
+    def current_tenant=(tenant)
+      TenantKit::Current.tenant = tenant
+    end
+  end
+end

data/lib/tenant_kit/current.rb

@@ -0,0 +1,16 @@
+require "active_support/current_attributes"
+
+module TenantKit
+  # Request-scoped holder for the current tenant, built on
+  # +ActiveSupport::CurrentAttributes+ so state is automatically reset between
+  # requests (and between jobs) — never a raw thread-local, which would bleed
+  # across requests on a reused thread.
+  class Current < ActiveSupport::CurrentAttributes
+    # @return [Object, nil] the current tenant record.
+    attribute :tenant
+
+    # Internal flag toggled by {TenantKit.without_tenant} to disable scoping.
+    # @return [Boolean, nil]
+    attribute :scoping_disabled
+  end
+end

data/lib/tenant_kit/errors.rb

@@ -0,0 +1,10 @@
+module TenantKit
+  # Base class for all TenantKit errors.
+  class Error < StandardError; end
+
+  # Raised when a tenant-scoped model is queried with no current tenant set,
+  # while strict mode (+config.require_tenant+) is enabled and execution is not
+  # inside a {TenantKit.without_tenant} block. Signals a would-be cross-tenant
+  # read rather than silently returning another tenant's data.
+  class NoTenantSet < Error; end
+end

data/lib/tenant_kit/job.rb

@@ -0,0 +1,55 @@
+require "global_id"
+
+module TenantKit
+  # Mixed into +ActiveJob::Base+ (via the railtie, when
+  # +config.propagate_to_jobs+ is true) so a job runs under the same tenant it
+  # was enqueued under — even though it executes later, in another process, with
+  # no request context.
+  #
+  # The tenant's GlobalID is captured at enqueue time and folded into the job's
+  # serialized payload (not just an in-memory attribute), so it survives any
+  # ActiveJob queue adapter — Solid Queue included — and is re-established around
+  # +perform+.
+  module Job
+    extend ActiveSupport::Concern
+
+    included do
+      # @return [String, nil] the enqueued tenant's GlobalID URI.
+      attr_accessor :tenant_kit_gid
+
+      around_enqueue do |job, block|
+        job.tenant_kit_gid ||= TenantKit::Current.tenant&.to_global_id&.to_s
+        block.call
+      end
+
+      around_perform do |job, block|
+        if job.tenant_kit_gid
+          tenant = GlobalID::Locator.locate(job.tenant_kit_gid)
+          TenantKit.with_tenant(tenant) { block.call }
+        elsif TenantKit.config.raise_on_missing_job_tenant
+          raise TenantKit::NoTenantSet, "Job #{job.class} enqueued without a tenant"
+        else
+          block.call
+        end
+      end
+    end
+
+    # Folds the captured tenant GlobalID into the serialized job payload so it
+    # round-trips through the queue adapter.
+    #
+    # @return [Hash]
+    def serialize
+      super.merge("tenant_kit_gid" => tenant_kit_gid)
+    end
+
+    # Restores the captured tenant GlobalID when the job is deserialized for
+    # execution.
+    #
+    # @param job_data [Hash]
+    # @return [void]
+    def deserialize(job_data)
+      super
+      self.tenant_kit_gid = job_data["tenant_kit_gid"]
+    end
+  end
+end

data/lib/tenant_kit/model.rb

@@ -0,0 +1,99 @@
+module TenantKit
+  # Mixed into every +ActiveRecord::Base+ (via the railtie). Provides the
+  # +belongs_to_tenant+ macro that turns a plain model into a tenant-owned one:
+  # it declares the tenant association, scopes all queries to the current tenant,
+  # auto-assigns the tenant on create, and validates the tenant's presence.
+  module Model
+    extend ActiveSupport::Concern
+
+    # Extended onto each tenant-owned model. Building a record evaluates the
+    # strict +default_scope+ via +scope_for_create+; without this guard,
+    # +Model.new+ with no current tenant would raise instead of letting presence
+    # validation report the missing tenant. We disable scoping only for the build
+    # itself — the subsequent +save+ (and its validations) runs normally.
+    module BuildGuard
+      def new(*args, **kwargs, &block)
+        TenantKit.without_tenant { super }
+      end
+    end
+
+    class_methods do
+      # Declares this model as tenant-owned.
+      #
+      # @param association [Symbol, nil] the tenant association name. Defaults to
+      #   the underscored {TenantKit::Configuration#tenant_class} (e.g. +:account+).
+      # @param options [Hash] forwarded to +belongs_to+ (+:class_name+,
+      #   +:foreign_key+, +:optional+, +:inverse_of+, ...).
+      # @option options [String] :foreign_key overrides
+      #   {TenantKit::Configuration#tenant_column}.
+      # @return [void]
+      #
+      # @example Default tenant
+      #   class Project < ApplicationRecord
+      #     belongs_to_tenant
+      #   end
+      #
+      # @example Explicit association
+      #   class Invoice < ApplicationRecord
+      #     belongs_to_tenant :account, class_name: "Account", foreign_key: "account_id"
+      #   end
+      def belongs_to_tenant(association = nil, **options)
+        assoc = (association || TenantKit.config.tenant_class.underscore).to_sym
+        fk    = (options[:foreign_key] || TenantKit.config.tenant_column).to_s
+
+        self._tenant_kit_association = assoc
+        self._tenant_kit_foreign_key = fk
+
+        extend TenantKit::Model::BuildGuard
+
+        belongs_to assoc, **options.slice(:class_name, :foreign_key, :optional, :inverse_of)
+
+        # Scope every read to the current tenant. Strict by default: querying with
+        # no tenant (and not inside without_tenant) raises rather than leaking.
+        default_scope do
+          if TenantKit.scoping_active?
+            where(fk => TenantKit::Current.tenant.public_send(:id))
+          elsif TenantKit.config.require_tenant && !TenantKit.scoping_disabled?
+            raise TenantKit::NoTenantSet, "No current tenant set for #{name}"
+          else
+            all
+          end
+        end
+
+        # Auto-assign the tenant on new records via before_validation — never via
+        # default_scope create behavior, which is a known foot-gun.
+        before_validation do
+          if TenantKit::Current.tenant && public_send(assoc).nil?
+            public_send("#{assoc}=", TenantKit::Current.tenant)
+          end
+        end
+
+        validates assoc, presence: true, unless: -> { TenantKit.scoping_disabled? }
+      end
+
+      # Validates that +attrs+ are unique within the current tenant, allowing the
+      # same value to reappear under a different tenant. The tenant foreign key is
+      # always folded into the uniqueness scope, so this must be called after
+      # {#belongs_to_tenant}.
+      #
+      # @param attrs [Array<Symbol>] attributes to check.
+      # @param opts [Hash] forwarded to the underlying uniqueness validation
+      #   (+:scope+, +:case_sensitive+, +:message+, +:conditions+, ...).
+      # @return [void]
+      def validates_uniqueness_to_tenant(*attrs, **opts)
+        unless _tenant_kit_foreign_key
+          raise ArgumentError, "call belongs_to_tenant before validates_uniqueness_to_tenant"
+        end
+
+        scope = (Array(opts[:scope]) + [ _tenant_kit_foreign_key.to_sym ]).uniq
+        validates_uniqueness_of(*attrs, **opts.merge(scope: scope))
+      end
+    end
+
+    included do
+      # The tenant association name and foreign key, set by belongs_to_tenant.
+      class_attribute :_tenant_kit_association, instance_accessor: false, default: nil
+      class_attribute :_tenant_kit_foreign_key, instance_accessor: false, default: nil
+    end
+  end
+end

data/lib/tenant_kit/railtie.rb

@@ -0,0 +1,35 @@
+# Ensure GlobalID is fully wired (GlobalID.app set, GlobalID::Identification
+# included into ActiveRecord::Base) — job propagation depends on it, and a host
+# app that doesn't otherwise use GlobalID (e.g. a --minimal app) won't have its
+# railtie loaded. Registering it here, at gem-load time, lets Rails run its
+# initializers during boot exactly as a full app would.
+require "global_id/railtie"
+
+module TenantKit
+  # Wires TenantKit into a Rails application on boot. Each concern is included
+  # only if it has been required, so the gem boots correctly at every build
+  # milestone. Hooks are guarded with +defined?+ so a partially-built gem never
+  # crashes the host app.
+  class Railtie < ::Rails::Railtie
+    initializer "tenant_kit.active_record" do
+      ActiveSupport.on_load(:active_record) do
+        include TenantKit::Model if defined?(TenantKit::Model)
+      end
+    end
+
+    initializer "tenant_kit.action_controller" do
+      ActiveSupport.on_load(:action_controller_base) do
+        include TenantKit::ControllerConcern if defined?(TenantKit::ControllerConcern)
+      end
+      ActiveSupport.on_load(:action_controller_api) do
+        include TenantKit::ControllerConcern if defined?(TenantKit::ControllerConcern)
+      end
+    end
+
+    initializer "tenant_kit.active_job" do
+      ActiveSupport.on_load(:active_job) do
+        include TenantKit::Job if defined?(TenantKit::Job) && TenantKit.config.propagate_to_jobs
+      end
+    end
+  end
+end

data/lib/tenant_kit/testing.rb

@@ -0,0 +1,34 @@
+module TenantKit
+  # Opt-in test helpers. Require and include where you need them — they are not
+  # loaded by default.
+  #
+  # @example RSpec
+  #   require "tenant_kit/testing"
+  #   RSpec.configure do |config|
+  #     config.include TenantKit::Testing
+  #     config.after { TenantKit::Current.reset }
+  #   end
+  #
+  #   it "does tenant work" do
+  #     as_tenant(account) { expect(Project.count).to eq(0) }
+  #   end
+  module Testing
+    # Runs the block scoped to +tenant+ (alias for {TenantKit.with_tenant}).
+    #
+    # @param tenant [Object]
+    # @yield the block to run under +tenant+.
+    # @return [Object] the block's return value.
+    def as_tenant(tenant, &block)
+      TenantKit.with_tenant(tenant, &block)
+    end
+
+    # Runs the block with tenant scoping disabled (alias for
+    # {TenantKit.without_tenant}).
+    #
+    # @yield the block to run unscoped.
+    # @return [Object] the block's return value.
+    def without_tenant(&block)
+      TenantKit.without_tenant(&block)
+    end
+  end
+end

data/lib/tenant_kit/version.rb

@@ -0,0 +1,3 @@
+module TenantKit
+  VERSION = "0.1.0"
+end

data/lib/tenant_kit.rb

@@ -0,0 +1,73 @@
+require "active_support"
+
+require "tenant_kit/version"
+require "tenant_kit/errors"
+require "tenant_kit/configuration"
+require "tenant_kit/current"
+require "tenant_kit/model"
+require "tenant_kit/controller_concern"
+require "tenant_kit/job"
+require "tenant_kit/railtie" if defined?(Rails::Railtie)
+
+# TenantKit — row-level (shared-schema) multi-tenancy for Rails.
+#
+# The module itself exposes configuration and the sanctioned ways to move in and
+# out of tenant scope: {with_tenant} and {without_tenant}. Everything else hangs
+# off {TenantKit::Current} (the request-scoped current tenant) and the
+# {TenantKit::Model} macro +belongs_to_tenant+.
+module TenantKit
+  class << self
+    # @return [TenantKit::Configuration] the singleton configuration object.
+    def config
+      @config ||= Configuration.new
+    end
+
+    # Yields the configuration for editing, typically from an initializer.
+    #
+    # @yieldparam config [TenantKit::Configuration]
+    # @return [TenantKit::Configuration]
+    def configure
+      yield config
+      config
+    end
+
+    # Runs the block with +tenant+ as the current tenant, restoring the previous
+    # tenant afterwards (even on error). The sanctioned way to switch tenants.
+    #
+    # @param tenant [Object] the tenant record to scope to.
+    # @yield the block to run under +tenant+.
+    # @return [Object] the block's return value.
+    def with_tenant(tenant)
+      previous = Current.tenant
+      Current.tenant = tenant
+      yield
+    ensure
+      Current.tenant = previous
+    end
+
+    # Runs the block with tenant scoping disabled — the single, greppable escape
+    # hatch for admin tools, seeds, migrations, and the console. Restores the
+    # previous state afterwards (even on error).
+    #
+    # @yield the block to run unscoped.
+    # @return [Object] the block's return value.
+    def without_tenant
+      was = Current.scoping_disabled
+      Current.scoping_disabled = true
+      yield
+    ensure
+      Current.scoping_disabled = was
+    end
+
+    # @return [Boolean] true when a tenant is set and scoping is not disabled —
+    #   i.e. queries should be filtered to the current tenant.
+    def scoping_active?
+      Current.tenant.present? && !Current.scoping_disabled
+    end
+
+    # @return [Boolean] true when inside a {without_tenant} block.
+    def scoping_disabled?
+      !!Current.scoping_disabled
+    end
+  end
+end

metadata

@@ -0,0 +1,114 @@
+--- !ruby/object:Gem::Specification
+name: tenant_kit
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- wintan1418
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+description: 'TenantKit makes a Rails app multi-tenant using the row-level / shared-schema
+  strategy: one database, a tenant_id foreign key on owned tables, automatic query
+  scoping via ActiveSupport::CurrentAttributes, auto-assignment of the current tenant,
+  and first-class tenant propagation into ActiveJob background jobs. It is strict
+  by default: querying a tenant-scoped model with no tenant set raises rather than
+  leaking another tenant''s data.'
+email:
+- wintan1418@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- MIT-LICENSE
+- README.md
+- Rakefile
+- lib/generators/tenant_kit/install/install_generator.rb
+- lib/generators/tenant_kit/install/templates/initializer.rb.tt
+- lib/generators/tenant_kit/install/templates/tenant_migration.rb.tt
+- lib/generators/tenant_kit/install/templates/tenant_model.rb.tt
+- lib/generators/tenant_kit/migration/migration_generator.rb
+- lib/generators/tenant_kit/migration/templates/add_tenant_reference.rb.tt
+- lib/tasks/tenant_kit_tasks.rake
+- lib/tenant_kit.rb
+- lib/tenant_kit/configuration.rb
+- lib/tenant_kit/controller_concern.rb
+- lib/tenant_kit/current.rb
+- lib/tenant_kit/errors.rb
+- lib/tenant_kit/job.rb
+- lib/tenant_kit/model.rb
+- lib/tenant_kit/railtie.rb
+- lib/tenant_kit/testing.rb
+- lib/tenant_kit/version.rb
+homepage: https://github.com/wintan1418/tenant_kit
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/wintan1418/tenant_kit
+  source_code_uri: https://github.com/wintan1418/tenant_kit/tree/main
+  changelog_uri: https://github.com/wintan1418/tenant_kit/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/wintan1418/tenant_kit/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Row-level (shared-schema) multi-tenancy for Rails, strict by default, with
+  background-job tenant propagation.
+test_files: []