tenant_partition 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4375402293baef4a0b28e50a004e57d25e2eff598f68d02d43056c7d5cdf51dc
-  data.tar.gz: c84e2003e7b8d812fec7edc2970fc6244a770d7bbfb81f64f9db0859663e8ae0
+  metadata.gz: 45c660ca7844d37613ad78edf986ebaf37d3ddb041d1d12f26fb6b0e59a22be3
+  data.tar.gz: 63a8b5b216e53866408ca4476dc2c0f5e17b818c72da540de2176d6582636d0d
 SHA512:
-  metadata.gz: 326a4ed3905b92f44a59b4dc22489e7f68b208f2e8e0a1d6195089a965acefbea35ad43763dcb5499c89859358eb0fac7a8dd84f8bdb506418170d09cef9d07b
-  data.tar.gz: 2eb2a9e5cdf25f74b26d58599bed33fe45d2c5fad0eaf7630298964ffbb014c1dc2c8335c538ca1f20df2a2a0e763c0d3fa0c7840cb5457c9909524b3b3faf4a
+  metadata.gz: af6c4fee560cdad57d5c430f07739a41d99fb1bb60e7e87ab04026c7d05a2ec98798e6f6730da4eba44cdd01e2133d6ec82e3f9aafd7fb182656a57ffd2d1ef5
+  data.tar.gz: a89e0a33ced5ab698892f6f48785a492ac2c3f467b92fe8f67d9e155479f3feb6745cc481cc975027d45569b880d6a5aef39c84be96afd07b7347291c7741a44

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 ## [Unreleased]
 
+## [0.1.2] - 2026-02-03
+### Added
+- Nuevo generador `rails g tenant_partition:api_controller` para crear endpoints de aprovisionamiento.
+- Soporte para namespaces dinámicos en el generador (ej: `rails g tenant_partition:api_controller Ops`).
+
 ## [0.1.1] - 2026-01-27
 - Refactor: Rename internal module to `TenantPartition`.
 - Fix: Update Rake tasks and Notifications to use `tenant_partition` namespace.

data/README.md

@@ -123,7 +123,19 @@ end
 TenantPartition.destroy!(old_isp.id)
 ```
 
-### 5. Seguridad en Controladores
+### 5. Generador de API (Provisioning)
+
+Para facilitar la integración con sistemas externos, la gema incluye un generador que crea un controlador base con las acciones `create`, `destroy` y `show` para tus tenants.
+
+**Uso Básico (Namespace por defecto `TenantPartition`):**
+
+```bash
+bundle exec rails g tenant_partition:api_controller
+# Crea: app/controllers/tenant_partition/tenant_partitions_controller.rb
+# Ruta: POST /tenant_partition/tenant_partitions
+```
+
+### 6. Seguridad en Controladores
 
 Protege tus API endpoints asegurando que siempre reciban el ID del tenant.
 

data/lib/generators/tenant_partition/api_controller_generator.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module TenantPartition
+  module Generators
+    # Generador encargado de crear el controlador API para la orquestación de tenants.
+    #
+    # Este generador facilita la creación de un punto de entrada (Endpoint) para que sistemas externos
+    # o administradores puedan gestionar el ciclo de vida de las particiones (Crear/Borrar/Consultar).
+    #
+    # Soporta la especificación de un **Namespace** opcional para organizar el controlador
+    # dentro de una carpeta específica (ej: `Ops`, `System`, `Admin`).
+    #
+    # @example Uso básico (Namespace por defecto: tenant_partition)
+    #   rails g tenant_partition:api_controller
+    #
+    # @example Uso con Namespace personalizado (ej: Ops)
+    #   rails g tenant_partition:api_controller Ops
+    #
+    class ApiControllerGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      # Define el argumento posicional para el namespace.
+      # Si el usuario no lo provee, se utiliza "system" por defecto.
+      #
+      # @!attribute [r] namespace_name
+      #   @return [String] El nombre del módulo/carpeta donde se alojará el controlador.
+      argument :namespace_name, type: :string, default: "system", banner: "namespace"
+
+      desc "Crea un controlador API profesional para gestionar el ciclo de vida de los Tenants, " \
+           "incluyendo rutas y boilerplate de seguridad."
+
+      # Genera el archivo del controlador utilizando la plantilla ERB.
+      #
+      # Calcula dinámicamente el nombre de la carpeta y del módulo basándose en el
+      # argumento `namespace_name` para asegurar que la estructura de archivos
+      # coincida con la nomenclatura de Ruby (CamelCase vs snake_case).
+      #
+      # @return [void]
+      def create_controller_file
+        # @module_name se usa dentro del template .erb para definir "module Ops"
+        @module_name = namespace_name.camelize
+
+        # folder_name define la ruta física: "app/controllers/ops/..."
+        folder_name  = namespace_name.underscore
+
+        template "tenant_partitions_controller.rb.erb",
+                 "app/controllers/#{folder_name}/tenant_partitions_controller.rb"
+      end
+
+      # Inyecta las rutas necesarias en el archivo `config/routes.rb` de la aplicación.
+      #
+      # Utiliza rutas directas en lugar de `namespace :xyz` para mantener la configuración
+      # de rutas lo más limpia y aislada posible, evitando bloques anidados innecesarios.
+      #
+      # @return [void]
+      def add_routes
+        folder_name = namespace_name.underscore
+
+        # Definición de rutas explícitas apuntando al controlador generado
+        route "post   '#{folder_name}/tenant_partitions', to: '#{folder_name}/tenant_partitions#create'"
+        route "delete '#{folder_name}/tenant_partitions/:id', to: '#{folder_name}/tenant_partitions#destroy'"
+        route "get    '#{folder_name}/tenant_partitions/:id', to: '#{folder_name}/tenant_partitions#show'"
+      end
+
+      # Muestra instrucciones post-generación en la consola.
+      #
+      # Es vital para advertir al usuario sobre la necesidad de configurar la seguridad (Autenticación),
+      # ya que el generador no puede asumir qué sistema de auth usa la aplicación (Devise, JWT, etc).
+      #
+      # @return [void]
+      def show_readme
+        # Solo mostramos el README si estamos generando (invoke), no borrando (revoke).
+        readme "README" if behavior == :invoke
+      end
+    end
+  end
+end

data/lib/generators/tenant_partition/templates/README

@@ -0,0 +1,13 @@
+===============================================================================
+👋 ¡Controlador de TenantPartition generado!
+
+Se ha creado: tenant_partitions_controller.rb
+Se han agregado rutas en: config/routes.rb
+
+⚠️  IMPORTANTE - SEGURIDAD ⚠️
+Por defecto, este controlador NO TIENE AUTENTICACIÓN.
+Cualquiera podría crear o borrar particiones si no lo proteges.
+
+1. Abre tenant_partitions_controller.rb
+2. Descomenta o agrega tu `before_action` de autenticación (ej: Devise).
+===============================================================================

data/lib/generators/tenant_partition/templates/tenant_partitions_controller.rb.erb

@@ -0,0 +1,36 @@
+module <%= @module_name %>
+  class TenantPartitionsController < ApplicationController
+    skip_before_action :verify_authenticity_token, raise: false
+
+    # POST /system/tenant_partitions
+    def create
+      partition_id = params.require(:id)
+
+      if TenantPartition.exists?(partition_id)
+        render json: { message: "Tenant already exists" }, status: :ok
+      else
+        TenantPartition.create!(partition_id)
+        render json: { message: "Tenant provisioned successfully" }, status: :created
+      end
+    rescue => e
+      render json: { error: e.message }, status: :unprocessable_entity
+    end
+
+    # DELETE /system/tenant_partitions/:id
+    def destroy
+      partition_id = params.require(:id)
+
+      TenantPartition.destroy!(partition_id)
+      head :no_content
+    end
+
+    # GET /system/tenant_partitions/:id
+    def show
+      if TenantPartition.exists?(params[:id])
+        render json: { active: true, id: params[:id] }, status: :ok
+      else
+        render json: { active: false }, status: :not_found
+      end
+    end
+  end
+end

data/lib/tenant_partition/base.rb

@@ -1,24 +1,21 @@
 # frozen_string_literal: true
 
+require_relative "concerns/data_mover"
+
 module TenantPartition
-  # Clase base para la gestión de infraestructura de particionamiento en PostgreSQL.
-  #
-  # Proporciona una interfaz para manejar el ciclo de vida de las tablas físicas (Particiones).
+  # Clase base abstracta para definir modelos de infraestructura de particionamiento.
+  # Hereda de esta clase para habilitar operaciones DDL (Create/Drop) sobre tus tablas particionadas.
   #
-  # @abstract Hereda de esta clase para definir un recurso de partición.
-  # @example
-  #   class Partition::Chat < TenantPartition::Base
-  #     # Opcional: Sobrescribir la clave global
-  #     self.partition_key = :region_code
-  #   end
+  # @abstract
   class Base
     include ActiveModel::Model
     include ActiveModel::Attributes
+    include TenantPartition::Concerns::DataMover
 
-    # Registra el atributo de partición en la subclase en el momento de la herencia.
+    # Hook de herencia para definir automáticamente el atributo de partición en las subclases.
+    # @param subclass [Class] La clase que hereda.
     def self.inherited(subclass)
       super
-      # Intentamos definir el atributo por defecto si existe configuración global
       key = TenantPartition.configuration&.partition_key
       subclass.attribute key if key
     end
@@ -26,39 +23,44 @@ module TenantPartition
     class << self
       attr_writer :parent_table, :prefix, :default_table
 
-      # Permite inyectar una clave de partición personalizada por clase
-      attr_writer :partition_key
-
+      # @return [String] Nombre de la tabla padre (ej: 'conversations').
       def parent_table
         @parent_table ||= name.demodulize.underscore.pluralize
       end
 
-      # Prioridad: 1. Clave de la clase, 2. Clave global
+      # @return [Symbol] Clave de partición configurada (ej: :isp_id).
+      # @raise [TenantPartition::Error] Si no hay configuración global ni local.
       def partition_key
         @partition_key ||= TenantPartition.configuration&.partition_key ||
-          raise(TenantPartition::Error, "Clave de partición no configurada.")
+                           raise(TenantPartition::Error, "Clave de partición no configurada.")
       end
 
+      # Define manualmente la clave de partición para esta clase, sobrescribiendo la global.
+      # @param value [Symbol] Nombre de la columna.
       def partition_key=(value)
         @partition_key = value
-        attribute value # Define el atributo en ActiveModel automáticamente
+        attribute value
       end
 
+      # @return [String] Prefijo para las tablas particionadas (ej: 'conversations_isp').
       def prefix
-        @prefix ||= "#{parent_table}_#{partition_key.to_s.gsub('_id', '')}"
+        @prefix ||= "#{parent_table}_#{partition_key.to_s.gsub("_id", "")}"
       end
 
+      # @return [String] Nombre de la tabla DEFAULT.
       def default_table
         @default_table ||= "#{parent_table}_default"
       end
 
+      # @return [ActiveRecord::ConnectionAdapters::PostgreSQLAdapter] Conexión activa a la DB.
       def connection
         ActiveRecord::Base.connection
       end
 
-      # Crea físicamente una partición en PostgreSQL.
+      # Crea una nueva partición física en la base de datos.
+      # @param value [String, Integer] El valor discriminador del tenant (ej: UUID).
+      # @return [TenantPartition::Base] Una instancia representando la nueva partición.
       def create(value)
-        # Importante: Usamos el método partition_key (no la variable) para respetar overrides
         payload = { partition_key: partition_key, value: value, table: parent_table }
 
         ActiveSupport::Notifications.instrument("create.tenant_partition", payload) do
@@ -69,14 +71,20 @@ module TenantPartition
         end
       end
 
+      # Genera el nombre físico de la tabla particionada, sanitizando el valor.
+      # @param value [Object] Valor del tenant.
+      # @return [String] Nombre de la tabla (ej: 'conversations_isp_123').
       def partition_name(value)
-        sanitized = value.to_s.gsub('-', '_')
+        sanitized = value.to_s.gsub("-", "_")
         "#{prefix}_#{sanitized}"
       end
 
+      # Verifica si la tabla particionada existe físicamente en el catálogo de PostgreSQL.
+      # @param value [Object] Valor del tenant.
+      # @return [Boolean] true si la tabla existe.
       def exists?(value)
         name = partition_name(value)
-        sql = <<-SQL.squish
+        sql = <<~SQL.squish
           SELECT 1 FROM pg_class c
           JOIN pg_inherits i ON c.oid = i.inhrelid
           JOIN pg_class p ON i.inhparent = p.oid
@@ -85,6 +93,9 @@ module TenantPartition
         connection.execute(sql).any?
       end
 
+      # Busca una partición existente.
+      # @param value [Object] Valor del tenant.
+      # @return [TenantPartition::Base, nil] Instancia si existe, nil si no.
       def find(value)
         new(partition_key => value) if exists?(value)
       end
@@ -92,63 +103,23 @@ module TenantPartition
 
     # --- Métodos de Instancia ---
 
+    # @return [Object] Valor del ID de partición de esta instancia.
     def partition_id
-      # CORRECCIÓN: Usamos public_send porque ActiveModel no tiene read_attribute
-      # Esto invoca al getter generado dinámicamente (ej: .isp_id)
       public_send(self.class.partition_key)
     end
 
+    # @return [String] Nombre de la tabla física correspondiente a esta instancia.
     def partition_table_name
       self.class.partition_name(partition_id)
     end
 
+    # @return [Boolean] Si la partición está persistida en base de datos.
     def persisted?
       self.class.exists?(partition_id)
     end
 
-    # Mueve registros desde la tabla por defecto hacia la partición atómicamente.
-    def populate_from_default(batch_size: 5000)
-      return 0 unless persisted?
-
-      parent  = self.class.parent_table
-      default = self.class.default_table
-      key     = self.class.partition_key
-      val     = partition_id
-
-      payload = { partition_key: key, value: val, parent_table: parent }
-
-      ActiveSupport::Notifications.instrument("populate.tenant_partition", payload) do |notification_payload|
-        total_moved = 0
-
-        loop do
-          batch_count = 0
-          self.class.connection.transaction do
-            # Usamos el ID para paginar el borrado/insertado
-            move_sql = <<-SQL.squish
-              WITH moved_rows AS (
-                DELETE FROM #{default}
-                WHERE #{key} = '#{val}'
-                AND id IN (
-                  SELECT id FROM #{default} WHERE #{key} = '#{val}' LIMIT #{batch_size}
-                )
-                RETURNING *
-              )
-              INSERT INTO #{parent} SELECT * FROM moved_rows;
-            SQL
-
-            result = self.class.connection.execute(move_sql)
-            batch_count = result.cmd_tuples
-          end
-
-          total_moved += batch_count
-          break if batch_count < batch_size
-        end
-
-        notification_payload[:count] = total_moved
-        total_moved
-      end
-    end
-
+    # Elimina la partición física de la base de datos (DETACH + DROP).
+    # @return [Boolean] true si la eliminación fue exitosa.
     def destroy
       return false unless persisted?
 

data/lib/tenant_partition/concerns/controller.rb

@@ -2,70 +2,46 @@
 
 module TenantPartition
   module Concerns
-    # Helpers y validaciones para controladores en arquitecturas Multi-tenant.
-    #
-    # Este módulo implementa una estrategia de extracción estricta:
-    # Solo acepta el ID de partición si viene en el Header HTTP configurado explícitamente.
-    #
-    # @example Configuración requerida
-    #   # config/initializers/tenant_partition.rb
-    #   TenantPartition.configure do |config|
-    #     config.partition_key = :isp_id
-    #     config.header_name = 'X-Tenant-ID' # <--- Obligatorio
-    #   end
-    #
-    # @example Uso en el controlador
-    #   class ApiController < ActionController::API
-    #     include TenantPartition::Concerns::Controller
-    #     before_action :require_partition_key!
-    #   end
+    # Concern para controladores que valida la presencia del Header de partición.
     module Controller
       extend ActiveSupport::Concern
 
       included do
-        # Expone el método a las vistas de Rails (erb, jbuilder, etc.)
         helper_method :current_partition_id if respond_to?(:helper_method)
       end
 
-      # Devuelve el valor del ID de partición actual extraído exclusivamente de los Headers.
-      #
-      # Utiliza únicamente el nombre de header definido en +TenantPartition.configuration.header_name+.
-      # No realiza inferencias ni busca en parámetros de la URL.
-      #
-      # @return [String, nil] El valor del header o nil si no está presente o configurado.
+      # Obtiene el ID de partición desde los headers de la petición.
+      # @return [String, nil] El valor del header configurado.
       def current_partition_id
         return @current_partition_id if defined?(@current_partition_id)
 
         header_key = TenantPartition.configuration.header_name
-
-        # Si no se configuró un nombre de header, no podemos buscar nada.
         return @current_partition_id = nil unless header_key.present?
 
         @current_partition_id = request.headers[header_key]
       end
 
-      # Filtro (before_action) para detener la ejecución si el ID de partición no está presente.
-      #
-      # Retorna un error 400 Bad Request si el header falta.
-      #
-      # @return [void]
+      # Filtro before_action para forzar la presencia del tenant.
+      # Renderiza un error 400 Bad Request si falta.
       def require_partition_key!
         return if current_partition_id.present?
 
-        header_key = TenantPartition.configuration.header_name
-
-        # Mensaje de error detallado dependiendo de si es un error de configuración o de petición
-        error_message = if header_key.blank?
-                          "Server Configuration Error: 'header_name' is not configured in TenantPartition."
-                        else
-                          "Missing required header: '#{header_key}'"
-                        end
-
         render json: {
           error: "Partitioning Error",
-          message: error_message
+          message: missing_header_message
         }, status: :bad_request
       end
+
+      private
+
+      def missing_header_message
+        header_key = TenantPartition.configuration.header_name
+        if header_key.blank?
+          "Server Configuration Error: 'header_name' is not configured in TenantPartition."
+        else
+          "Missing required header: '#{header_key}'"
+        end
+      end
     end
   end
 end

data/lib/tenant_partition/concerns/data_mover.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module TenantPartition
+  module Concerns
+    # Módulo encargado de la migración de datos (Backfilling) entre tablas.
+    # Se extrajo de {TenantPartition::Base} para desacoplar la lógica de movimiento de datos.
+    module DataMover
+      extend ActiveSupport::Concern
+
+      # Query SQL parametrizada para el movimiento atómico (DELETE + INSERT).
+      # Se define como constante para evitar la ofensa Metrics/MethodLength de RuboCop
+      # y mejorar la performance evitando la re-asignación de memoria en cada llamada.
+      # @api private
+      MOVE_SQL = <<~SQL.squish.freeze
+        WITH moved_rows AS (
+          DELETE FROM %<default>s
+          WHERE %<key>s = '%<val>s'
+          AND id IN (
+            SELECT id FROM %<default>s WHERE %<key>s = '%<val>s' LIMIT %<batch_size>d
+          )
+          RETURNING *
+        )
+        INSERT INTO %<parent>s SELECT * FROM moved_rows;
+      SQL
+      private_constant :MOVE_SQL
+
+      # Mueve registros desde la tabla DEFAULT hacia la partición actual.
+      # Utiliza transacciones por lotes para evitar bloqueos prolongados en la base de datos.
+      #
+      # @param batch_size [Integer] Cantidad de registros por transacción (Default: 5000).
+      # @return [Integer] La cantidad total de registros movidos exitosamente.
+      def populate_from_default(batch_size: 5000)
+        return 0 unless persisted?
+
+        ActiveSupport::Notifications.instrument("populate.tenant_partition", instrumentation_payload) do |evt|
+          total = perform_batch_move(batch_size)
+          evt[:count] = total
+          total
+        end
+      end
+
+      private
+
+      # Construye el payload de datos para la instrumentación de ActiveSupport.
+      # @return [Hash] Datos del contexto de la migración.
+      def instrumentation_payload
+        {
+          partition_key: self.class.partition_key,
+          value: partition_id,
+          parent_table: self.class.parent_table
+        }
+      end
+
+      # Ejecuta el bucle de movimiento hasta que no queden registros pendientes.
+      # @param batch_size [Integer] Tamaño del lote.
+      # @return [Integer] Total acumulado de registros movidos.
+      def perform_batch_move(batch_size)
+        total_moved = 0
+        loop do
+          batch_count = move_single_batch(batch_size)
+          total_moved += batch_count
+          break if batch_count < batch_size
+        end
+        total_moved
+      end
+
+      # Ejecuta una transacción atómica para mover un solo lote de registros.
+      # @param batch_size [Integer] Tamaño del lote.
+      # @return [Integer] Cantidad de filas afectadas (cmd_tuples).
+      def move_single_batch(batch_size)
+        self.class.connection.transaction do
+          # Kernel#format es más rápido y seguro que la interpolación directa para templates
+          sql = format(MOVE_SQL, move_query_params(batch_size))
+          self.class.connection.execute(sql).cmd_tuples
+        end
+      end
+
+      # Prepara los parámetros para inyectar en la plantilla SQL.
+      # Se extrajo a un método separado para reducir la longitud de `move_single_batch`.
+      # @param batch_size [Integer] Tamaño del lote.
+      # @return [Hash] Parámetros formateados para Kernel#format.
+      def move_query_params(batch_size)
+        {
+          default: self.class.default_table,
+          parent: self.class.parent_table,
+          key: self.class.partition_key,
+          val: partition_id,
+          batch_size: batch_size
+        }
+      end
+    end
+  end
+end