feedkit 0.1.0

data/lib/feedkit/engine.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Feedkit
+  class Engine < ::Rails::Engine
+    isolate_namespace Feedkit
+
+    config.generators do |g|
+      g.test_framework :minitest, fixture: false
+    end
+
+    initializer "feedkit.set_configs" do
+      Feedkit.configuration.logger ||= Rails.logger
+    end
+  end
+end

data/lib/feedkit/feeds_owner.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Feedkit
+  module FeedsOwner
+    extend ActiveSupport::Concern
+
+    included do
+      has_many Feedkit.configuration.association_name,
+               class_name: "Feedkit::Feed",
+               as: :owner,
+               dependent: :delete_all
+    end
+  end
+end

data/lib/feedkit/generator.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Feedkit
+  class Generator
+    include Schedulable
+
+    class << self
+      def inherited(subclass)
+        super
+
+        Feedkit::Registry.register(subclass)
+      end
+
+      def owned_by(type = nil)
+        @owner_class = type || @owner_class
+      end
+
+      def owner_class
+        return @owner_class.constantize if @owner_class.is_a?(String)
+
+        @owner_class
+      end
+
+      def feed_type
+        name.demodulize.underscore.to_sym
+      end
+
+      def scheduled?
+        schedules.any?
+      end
+    end
+
+    def initialize(owner = nil, period_name: nil, **options)
+      @owner = owner
+      @options = options
+      @schedule = period_name ? self.class.find_schedule(period_name) : nil
+
+      raise ArgumentError, "Unknown schedule: #{period_name}" if period_name && !@schedule
+    end
+
+    def call
+      return if already_generated?
+      return unless (payload = data)
+
+      create_feed!(payload)
+    end
+
+    private
+
+    attr_reader :owner, :options
+
+    def data
+      raise NotImplementedError, "#{self.class.name} must implement #data"
+    end
+
+    def period
+      @schedule&.period
+    end
+
+    def period_name
+      @schedule&.period_name
+    end
+
+    def already_generated?
+      return false unless @schedule
+      return false unless @owner
+
+      feed_scope.where(feed_type: self.class.feed_type, period_name: period_name)
+                .exists?(["created_at > ?", period.ago])
+    end
+
+    def create_feed!(payload)
+      if @owner
+        feed_scope.create!(feed_type: self.class.feed_type, period_name: period_name, data: payload)
+      else
+        Feedkit::Feed.create!(feed_type: self.class.feed_type, period_name: period_name, data: payload)
+      end
+    end
+
+    def feed_scope
+      @owner.public_send(Feedkit.configuration.association_name)
+    end
+  end
+end

data/lib/feedkit/registry.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Feedkit
+  # Tracks all generator classes via the inherited hook in Feedkit::Generator.
+  # Registration happens at class load time (boot), not during requests,
+  # so thread-safety of the underlying Set is not a concern in practice.
+  module Registry
+    class << self
+      def generators
+        @generators ||= Set.new
+      end
+
+      def register(klass)
+        generators << klass
+      end
+
+      def unregister(klass)
+        generators.delete(klass)
+      end
+
+      def clear!
+        @generators = Set.new
+      end
+
+      # Returns generators that have schedules defined.
+      def scheduled_generators
+        generators.select(&:scheduled?)
+      end
+
+      # Returns scheduled generators that also have an owner class.
+      # Only these can be dispatched automatically, since DispatchJob
+      # iterates over owner records to enqueue GenerateFeedJob.
+      def dispatchable_generators
+        scheduled_generators.select(&:owner_class)
+      end
+
+      def generators_for_owner(owner_class)
+        generators.select { |g| g.owner_class == owner_class }
+      end
+
+      def due_at(time = Time.current)
+        Feedkit.eager_load_generators!
+
+        dispatchable_generators.flat_map do |generator|
+          generator.schedules_due(time).map do |schedule|
+            { generator: generator, period_name: schedule.period_name }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/feedkit/schedulable.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Feedkit
+  module Schedulable
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def schedules
+        @schedules ||= []
+      end
+
+      def schedule(every:, at:, as: nil, superseded_by: [])
+        schedules << Feedkit::Schedule.new(every: every, at: at, as: as, superseded_by: superseded_by)
+      end
+
+      def schedules_due(time = Time.current)
+        due = schedules.select { |s| s.due?(time) }
+        due_names = due.map(&:period_name)
+        due.reject { |s| s.superseded_by.any? { |name| due_names.include?(name) } }
+      end
+
+      def find_schedule(period_name)
+        schedules.find { |s| s.period_name == period_name&.to_s }
+      end
+    end
+  end
+end

data/lib/feedkit/schedule.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+module Feedkit
+  class Schedule # rubocop:disable Metrics/ClassLength
+    VALID_CONDITION_TYPES = %i[hour day weekday week month].freeze
+    VALID_HOUR_RANGE = (0..23)
+    VALID_DAY_RANGE = (1..31)
+    VALID_WEEKDAY_RANGE = (0..6)
+    VALID_WEEK_RANGE = (1..53)
+    VALID_MONTH_RANGE = (1..12)
+    SYMBOLIC_DAY_VALUES = %i[first last].freeze
+    SYMBOLIC_WEEK_VALUES = %i[even odd].freeze
+
+    WEEKDAYS = {
+      sunday: 0,
+      monday: 1,
+      tuesday: 2,
+      wednesday: 3,
+      thursday: 4,
+      friday: 5,
+      saturday: 6
+    }.freeze
+
+    MONTHS = {
+      january: 1,
+      february: 2,
+      march: 3,
+      april: 4,
+      may: 5,
+      june: 6,
+      july: 7,
+      august: 8,
+      september: 9,
+      october: 10,
+      november: 11,
+      december: 12
+    }.freeze
+
+    CONDITION_ABBREVIATIONS = {
+      hour: "h",
+      day: "d",
+      weekday: "wd",
+      week: "w",
+      month: "m"
+    }.freeze
+
+    attr_reader :period_name, :period, :conditions, :superseded_by
+
+    def initialize(every:, at:, as: nil, superseded_by: [])
+      @period = every
+      @conditions = at
+      @superseded_by = Array(superseded_by).map(&:to_s)
+
+      validate_conditions!
+
+      @period_name = (as || generate_period_name).to_s
+    end
+
+    def due?(time = Time.current)
+      conditions.all? { |type, value| matches?(type, value, time) }
+    end
+
+    private
+
+    def validate_conditions!
+      raise ArgumentError, "conditions must be a Hash" unless conditions.is_a?(Hash)
+
+      conditions.each { |type, value| validate_condition!(type, value) }
+    end
+
+    def validate_condition!(type, value)
+      unless VALID_CONDITION_TYPES.include?(type)
+        raise ArgumentError, "Unknown condition type: #{type}. Valid types: #{VALID_CONDITION_TYPES.join(", ")}"
+      end
+
+      validate_condition_value!(type, value)
+    end
+
+    def validate_condition_value!(type, value)
+      case value
+      when Range then validate_range_value!(type, value)
+      when Array then value.each { |v| validate_scalar_value!(type, v) }
+      else validate_scalar_value!(type, value)
+      end
+    end
+
+    def validate_range_value!(type, range)
+      validate_scalar_value!(type, range.begin)
+      validate_scalar_value!(type, range.end)
+    end
+
+    def validate_scalar_value!(type, value)
+      case type
+      when :hour    then validate_hour_value!(value)
+      when :day     then validate_day_value!(value)
+      when :weekday then validate_weekday_value!(value)
+      when :week    then validate_week_value!(value)
+      when :month   then validate_month_value!(value)
+      end
+    end
+
+    def validate_hour_value!(value)
+      return if value.is_a?(Integer) && VALID_HOUR_RANGE.cover?(value)
+
+      raise ArgumentError, "Invalid hour value: #{value}. Must be integer 0-23"
+    end
+
+    def validate_day_value!(value)
+      return if SYMBOLIC_DAY_VALUES.include?(value)
+      return if value.is_a?(Integer) && VALID_DAY_RANGE.cover?(value)
+
+      raise ArgumentError, "Invalid day value: #{value}. Must be integer 1-31 or :first/:last"
+    end
+
+    def validate_weekday_value!(value)
+      return if WEEKDAYS.key?(value)
+      return if value.is_a?(Integer) && VALID_WEEKDAY_RANGE.cover?(value)
+
+      raise ArgumentError,
+            "Invalid weekday value: #{value}. Must be integer 0-6 or symbol (#{WEEKDAYS.keys.join(", ")})"
+    end
+
+    def validate_week_value!(value)
+      return if SYMBOLIC_WEEK_VALUES.include?(value)
+      return if value.is_a?(Integer) && VALID_WEEK_RANGE.cover?(value)
+
+      raise ArgumentError, "Invalid week value: #{value}. Must be integer 1-53 or :even/:odd"
+    end
+
+    def validate_month_value!(value)
+      return if MONTHS.key?(value)
+      return if value.is_a?(Integer) && VALID_MONTH_RANGE.cover?(value)
+
+      raise ArgumentError, "Invalid month value: #{value}. Must be integer 1-12 or symbol (#{MONTHS.keys.join(", ")})"
+    end
+
+    def matches?(type, value, time)
+      actual = actual_value_for(type, time)
+      value = normalize_weekday(value) if type == :weekday
+      value = normalize_month(value) if type == :month
+
+      case value
+      when Range  then value.cover?(actual)
+      when Array  then value.include?(actual)
+      when Symbol then symbolic_match?(value, type, time)
+      else value == actual
+      end
+    end
+
+    def actual_value_for(type, time)
+      case type
+      when :hour    then time.hour
+      when :day     then time.day
+      when :weekday then time.wday
+      when :week    then time.to_date.cweek
+      when :month   then time.month
+      end
+    end
+
+    def symbolic_match?(value, type, time)
+      case [type, value]
+      when %i[day last]  then time.day == time.end_of_month.day
+      when %i[day first] then time.day == 1
+      when %i[week even] then time.to_date.cweek.even?
+      when %i[week odd]  then time.to_date.cweek.odd?
+      end
+    end
+
+    def generate_period_name
+      parts = [period_abbreviation]
+      conditions.each do |type, value|
+        parts << "#{condition_abbreviation(type)}#{condition_value(type, value)}"
+      end
+      parts.join("_")
+    end
+
+    def period_abbreviation
+      case period
+      when 1.hour  then "h1"
+      when 1.day   then "d1"
+      when 1.week  then "w1"
+      when 2.weeks then "w2"
+      when 1.month then "m1"
+      when 1.year  then "y1"
+      else "s#{period.to_i}"
+      end
+    end
+
+    def condition_abbreviation(type)
+      CONDITION_ABBREVIATIONS[type]
+    end
+
+    def condition_value(type, value)
+      value = normalize_weekday(value) if type == :weekday
+      value = normalize_month(value) if type == :month
+
+      case value
+      when Range then "#{value.begin}-#{value.end}"
+      when Array then value.join("-")
+      else value
+      end
+    end
+
+    def normalize_weekday(value)
+      case value
+      when Symbol then WEEKDAYS.fetch(value, value)
+      when Range  then normalize_weekday(value.begin)..normalize_weekday(value.end)
+      when Array  then value.map { |v| normalize_weekday(v) }
+      else value
+      end
+    end
+
+    def normalize_month(value)
+      case value
+      when Symbol then MONTHS.fetch(value, value)
+      when Range  then normalize_month(value.begin)..normalize_month(value.end)
+      when Array  then value.map { |v| normalize_month(v) }
+      else value
+      end
+    end
+  end
+end

data/lib/feedkit/version.rb

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

data/lib/feedkit.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "active_support"
+
+require_relative "feedkit/version"
+require_relative "feedkit/configuration"
+require_relative "feedkit/schedule"
+require_relative "feedkit/schedulable"
+require_relative "feedkit/registry"
+require_relative "feedkit/generator"
+require_relative "feedkit/feeds_owner"
+
+module Feedkit
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def logger
+      configuration.logger || (defined?(Rails) ? Rails.logger : Logger.new($stdout))
+    end
+
+    def eager_load_generators!
+      return if @generators_loaded
+      return if defined?(Rails) && Rails.application.config.eager_load
+
+      configuration.generator_paths.each do |path|
+        pattern = defined?(Rails) ? Rails.root.join(path) : path
+        Dir[pattern].each { |file| require file }
+      end
+
+      @generators_loaded = true
+    end
+
+    def reset_eager_load!
+      @generators_loaded = false
+    end
+  end
+end
+
+require_relative "feedkit/engine" if defined?(Rails::Engine)

data/lib/generators/feedkit/generator_generator.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module Feedkit
+  module Generators
+    class GeneratorGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      class_option :owner,
+                   type: :string,
+                   default: nil,
+                   desc: "The owner model class name (e.g., Organization)"
+
+      def create_generator_file
+        template "generator.rb.tt", "app/generators/#{file_name}.rb"
+      end
+
+      def create_test_file
+        template "generator_test.rb.tt", "test/generators/#{file_name}_test.rb"
+      end
+
+      private
+
+      def owner_class
+        options[:owner]
+      end
+
+      def owner?
+        owner_class.present?
+      end
+    end
+  end
+end

data/lib/generators/feedkit/install_generator.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/migration"
+
+module Feedkit
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      class_option :owner_id_type,
+                   type: :string,
+                   default: "bigint",
+                   desc: "The type for owner_id column (bigint or uuid)"
+
+      def self.next_migration_number(dirname)
+        if ActiveRecord::Base.timestamped_migrations
+          Time.now.utc.strftime("%Y%m%d%H%M%S")
+        else
+          format("%<number>.3d", number: (current_migration_number(dirname) + 1))
+        end
+      end
+
+      def create_initializer
+        template "initializer.rb.tt", "config/initializers/feedkit.rb"
+      end
+
+      def create_migration
+        migration_template "migration.rb.tt", "db/migrate/create_feedkit_feeds.rb"
+      end
+
+      def create_generators_directory
+        empty_directory "app/generators"
+        create_file "app/generators/.keep"
+      end
+
+      private
+
+      def owner_id_type
+        options[:owner_id_type]
+      end
+    end
+  end
+end

data/lib/generators/feedkit/templates/generator.rb.tt

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+class <%= class_name %> < Feedkit::Generator
+<% if owner? -%>
+  owned_by <%= owner_class %>
+
+<% end -%>
+  # Define schedules for automatic feed generation
+  # schedule every: 1.day, at: { hour: 6 }, as: :daily
+  # schedule every: 1.week, at: { hour: 7, weekday: :monday }, as: :weekly
+
+  private
+
+  def data
+    # Return a hash with the feed data, or nil to skip feed creation
+    # Example:
+    # {
+    #   total_count: calculate_total,
+    #   items: fetch_items
+    # }
+    raise NotImplementedError, '<%= class_name %> must implement #data'
+  end
+end

data/lib/generators/feedkit/templates/generator_test.rb.tt

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'test_helper'
+
+class <%= class_name %>Test < ActiveSupport::TestCase
+<% if owner? -%>
+  # setup do
+  #   @owner = <%= owner_class.underscore.pluralize %>(:one)
+  # end
+
+<% end -%>
+  test 'owner_class returns the configured owner type' do
+<% if owner? -%>
+    assert_equal <%= owner_class %>, <%= class_name %>.owner_class
+<% else -%>
+    assert_nil <%= class_name %>.owner_class
+<% end -%>
+  end
+
+  test 'feed_type returns underscored class name' do
+    assert_equal :<%= file_name %>, <%= class_name %>.feed_type
+  end
+
+  # test 'call creates a feed with expected data' do
+<% if owner? -%>
+  #   generator = <%= class_name %>.new(@owner, period_name: :daily)
+<% else -%>
+  #   generator = <%= class_name %>.new(nil)
+<% end -%>
+  #
+  #   assert_difference 'Feedkit::Feed.count', 1 do
+  #     generator.call
+  #   end
+  #
+  #   feed = Feedkit::Feed.last
+  #   assert_equal '<%= file_name %>', feed.feed_type
+  # end
+end

data/lib/generators/feedkit/templates/initializer.rb.tt

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+Feedkit.configure do |config|
+  # Table name for feeds (default: 'feedkit_feeds')
+  # config.table_name = 'feedkit_feeds'
+
+  # Association name for the feeds relationship (default: :feeds)
+  # config.association_name = :feeds
+
+  # Paths to search for generator classes (default: ['app/generators/**/*.rb'])
+  # config.generator_paths = ['app/generators/**/*.rb']
+
+  # Primary key type for owner_id (default: :bigint)
+  # Set to :uuid if your models use UUID primary keys
+  config.owner_id_type = :<%= owner_id_type %>
+
+  # Logger for Feedkit (defaults to Rails.logger)
+  # config.logger = Rails.logger
+end

data/lib/generators/feedkit/templates/migration.rb.tt

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+class CreateFeedkitFeeds < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :feedkit_feeds do |t|
+      t.string :owner_type
+      t.<%= owner_id_type %> :owner_id
+      t.string :feed_type, null: false
+      t.string :period_name
+      t.jsonb :data, null: false, default: {}
+
+      t.timestamps
+    end
+
+    add_index :feedkit_feeds, :created_at
+    add_index :feedkit_feeds, %i[owner_type owner_id feed_type created_at], name: 'idx_feedkit_feeds_lookup'
+    add_index :feedkit_feeds, %i[owner_type owner_id feed_type period_name], name: 'idx_feedkit_feeds_dedup'
+  end
+end