sitemap_generator-cache_adapter 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: febec451f961b8b328763defdc44cb4b1cc9c2d294ef2f9979f479c04b5b0d40
+  data.tar.gz: 85f82fd0768b2f4e1d86c8304f50ab2b529c2aea9901bf52981f970102255eef
+SHA512:
+  metadata.gz: 9bc7e95fad17474e16acb7975c1e5a1ed4d2298ac5af25609e05b677aea4476a2b8975b42b61d8a8faba8408d7e57f6df2fd681933a3757f97701b777fbc569c
+  data.tar.gz: 5290c796fc45b8a71a9a6828d5da2b6985fed371b903f43f8754f90db91121741f49098b5be3c166ac190e2388ed175ce9c8526c7e4df9985811091631bc842f

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-01-09
+
+### Added
+
+- Initial release
+- `SitemapGenerator::CacheAdapter` class for storing sitemaps in Rails.cache
+- Support for custom cache key prefix and expiration time
+- Support for custom cache store
+- Class methods: `fetch`, `read`, `exist?`, `delete`, `clear_all`
+- Comprehensive documentation and examples

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Steve Hill
+
+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,180 @@
+# SitemapGenerator::CacheAdapter
+
+A cache-based storage adapter for the [sitemap_generator](https://github.com/kjvarga/sitemap_generator) gem. Stores sitemaps in `Rails.cache` instead of the filesystem.
+
+## Why?
+
+The default `sitemap_generator` adapter writes sitemaps to disk. This doesn't work well for:
+
+- **Kubernetes deployments** with ephemeral pod storage
+- **Heroku** and other read-only filesystems
+- **Multi-pod deployments** where sitemaps need to be shared across instances
+- **Serverless environments** without persistent storage
+
+This adapter stores sitemaps in your Rails cache instead. When used with a database-backed cache like [Solid Cache](https://github.com/rails/solid_cache), sitemaps persist across deploys and are shared across all application instances.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "sitemap_generator-cache_adapter"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Usage
+
+### Basic Setup
+
+Configure `sitemap_generator` to use the cache adapter in `config/sitemap.rb`:
+
+```ruby
+SitemapGenerator::Sitemap.default_host = "https://example.com"
+SitemapGenerator::Sitemap.adapter = SitemapGenerator::CacheAdapter.new
+SitemapGenerator::Sitemap.compress = false  # Recommended for cache storage
+SitemapGenerator::Sitemap.create_index = false  # Single sitemap file
+
+SitemapGenerator::Sitemap.create do
+  add "/about", changefreq: "monthly"
+  add "/contact", changefreq: "monthly"
+
+  # Add dynamic content
+  Post.find_each do |post|
+    add post_path(post), lastmod: post.updated_at
+  end
+end
+```
+
+### Serving Sitemaps
+
+Create a controller to serve sitemaps from the cache:
+
+```ruby
+# app/controllers/sitemaps_controller.rb
+class SitemapsController < ApplicationController
+  def show
+    xml = SitemapGenerator::CacheAdapter.fetch("sitemap.xml") do
+      # This block runs on cache miss - generates and caches the sitemap
+      SitemapGenerator::Sitemap.create
+    end
+
+    if xml.present?
+      render xml: xml
+    else
+      head :not_found
+    end
+  end
+end
+```
+
+Add the route:
+
+```ruby
+# config/routes.rb
+get "sitemap.xml", to: "sitemaps#show", defaults: { format: :xml }
+```
+
+### Configuration Options
+
+```ruby
+SitemapGenerator::Sitemap.adapter = SitemapGenerator::CacheAdapter.new(
+  cache_key_prefix: "myapp:sitemap",  # Default: "sitemap_generator"
+  expires_in: 12.hours,               # Default: 24.hours
+  cache_store: Rails.cache            # Default: Rails.cache
+)
+```
+
+### Class Methods
+
+The adapter provides several class methods for working with cached sitemaps:
+
+```ruby
+# Fetch with lazy generation
+xml = SitemapGenerator::CacheAdapter.fetch("sitemap.xml") do
+  SitemapGenerator::Sitemap.create
+end
+
+# Read directly (returns nil if not cached)
+xml = SitemapGenerator::CacheAdapter.read("sitemap.xml")
+
+# Check existence
+if SitemapGenerator::CacheAdapter.exist?("sitemap.xml")
+  # ...
+end
+
+# Delete a specific sitemap
+SitemapGenerator::CacheAdapter.delete("sitemap.xml")
+
+# Clear all cached sitemaps
+SitemapGenerator::CacheAdapter.clear_all
+```
+
+## How It Works
+
+1. **On cache miss**: The `fetch` method yields to the block, which calls `SitemapGenerator::Sitemap.create`. This triggers the adapter's `write` method, storing the sitemap XML in the cache.
+
+2. **On cache hit**: The cached XML is returned immediately without regeneration.
+
+3. **Expiration**: Sitemaps expire after 24 hours by default. On the next request after expiration, a fresh sitemap is generated.
+
+This "lazy regeneration" approach means:
+- No scheduled jobs required
+- Sitemaps are always fresh (within the cache TTL)
+- First request after expiration may be slightly slower
+
+## Cache Backend Compatibility
+
+Works with any Rails cache backend:
+
+- **Solid Cache** (recommended for Kubernetes) - Database-backed, shared across pods
+- **Redis** - Fast, shared across pods
+- **Memcached** - Fast, shared across pods
+- **Memory Store** - Development/testing only (not shared)
+- **File Store** - Single-server deployments only
+
+## Example: Kubernetes with Solid Cache
+
+```ruby
+# Gemfile
+gem "solid_cache"
+gem "sitemap_generator"
+gem "sitemap_generator-cache_adapter"
+
+# config/environments/production.rb
+config.cache_store = :solid_cache_store
+
+# config/sitemap.rb
+SitemapGenerator::Sitemap.adapter = SitemapGenerator::CacheAdapter.new
+```
+
+With this setup, sitemaps are stored in your database and accessible from any pod in your cluster.
+
+## Migrating from File-Based Sitemaps
+
+1. Add the gem to your Gemfile
+2. Update `config/sitemap.rb` to use the cache adapter
+3. Create the sitemaps controller and route
+4. Remove any sitemap-related cron jobs or scheduled tasks
+5. Add `public/sitemap*.xml` to `.gitignore`
+6. Delete existing static sitemap files
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec standardrb
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE).

data/lib/sitemap_generator/cache_adapter/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module SitemapGenerator
+  class CacheAdapter
+    VERSION = "1.0.0"
+  end
+end

data/lib/sitemap_generator/cache_adapter.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+require "sitemap_generator"
+
+module SitemapGenerator
+  # An adapter for SitemapGenerator that stores sitemaps in Rails.cache instead of the filesystem.
+  #
+  # This is useful for:
+  # - Kubernetes deployments with no persistent disk storage
+  # - Heroku and other read-only/ephemeral filesystems
+  # - Multi-pod deployments where sitemaps need to be shared across instances
+  #
+  # When used with a database-backed cache (like Solid Cache), sitemaps persist
+  # across deploys and are shared across all application instances.
+  #
+  # @example Basic usage in config/sitemap.rb
+  #   SitemapGenerator::Sitemap.adapter = SitemapGenerator::CacheAdapter.new
+  #
+  # @example With custom options
+  #   SitemapGenerator::Sitemap.adapter = SitemapGenerator::CacheAdapter.new(
+  #     cache_key_prefix: "myapp:sitemap",
+  #     expires_in: 12.hours
+  #   )
+  #
+  # @example Serving from a Rails controller
+  #   class SitemapsController < ApplicationController
+  #     def show
+  #       xml = SitemapGenerator::CacheAdapter.fetch("sitemap.xml") do
+  #         SitemapGenerator::Sitemap.create
+  #       end
+  #       render xml: xml
+  #     end
+  #   end
+  #
+  class CacheAdapter
+    DEFAULT_CACHE_KEY_PREFIX = "sitemap_generator"
+    DEFAULT_EXPIRES_IN = 86_400 # 24 hours in seconds
+
+    class << self
+      # @return [String] The prefix used for all cache keys
+      def cache_key_prefix
+        @cache_key_prefix || DEFAULT_CACHE_KEY_PREFIX
+      end
+
+      # @param value [String] The prefix to use for all cache keys
+      attr_writer :cache_key_prefix
+
+      # @return [Integer, ActiveSupport::Duration] The cache expiration time
+      def expires_in
+        @expires_in || DEFAULT_EXPIRES_IN
+      end
+
+      # @param value [Integer, ActiveSupport::Duration] The cache expiration time
+      attr_writer :expires_in
+
+      # @return [#fetch, #read, #write, #exist?, #delete] The cache store to use
+      def cache_store
+        @cache_store || default_cache_store
+      end
+
+      # @param value [#fetch, #read, #write, #exist?, #delete] The cache store to use
+      attr_writer :cache_store
+
+      # Fetch a sitemap from cache, generating it if not present.
+      #
+      # @param filename [String] The sitemap filename (e.g., "sitemap.xml")
+      # @yield Block that generates the sitemap (typically calls SitemapGenerator::Sitemap.create)
+      # @return [String] The sitemap XML content
+      #
+      # @example
+      #   xml = SitemapGenerator::CacheAdapter.fetch("sitemap.xml") do
+      #     SitemapGenerator::Sitemap.create
+      #   end
+      def fetch(filename, &block)
+        cache_key = "#{cache_key_prefix}:#{filename}"
+
+        cache_store.fetch(cache_key, expires_in: expires_in) do
+          yield if block_given?
+          cache_store.read(cache_key)
+        end
+      end
+
+      # Read a sitemap directly from cache without generation.
+      #
+      # @param filename [String] The sitemap filename
+      # @return [String, nil] The sitemap XML content or nil if not cached
+      def read(filename)
+        cache_store.read("#{cache_key_prefix}:#{filename}")
+      end
+
+      # Check if a sitemap exists in cache.
+      #
+      # @param filename [String] The sitemap filename
+      # @return [Boolean]
+      def exist?(filename)
+        cache_store.exist?("#{cache_key_prefix}:#{filename}")
+      end
+
+      # Delete a specific sitemap from cache.
+      #
+      # @param filename [String] The sitemap filename
+      # @return [Boolean] true if deleted, false otherwise
+      def delete(filename)
+        cache_store.delete("#{cache_key_prefix}:#{filename}")
+      end
+
+      # Clear all cached sitemaps matching the prefix.
+      #
+      # @note This only works with cache stores that support delete_matched
+      # @return [void]
+      def clear_all
+        if cache_store.respond_to?(:delete_matched)
+          cache_store.delete_matched("#{cache_key_prefix}:*")
+        else
+          # Fallback: delete known sitemap filenames
+          %w[sitemap.xml sitemap.xml.gz sitemap_index.xml sitemap_index.xml.gz].each do |f|
+            delete(f)
+          end
+        end
+      end
+
+      # Reset configuration to defaults.
+      #
+      # @return [void]
+      def reset!
+        @cache_key_prefix = nil
+        @expires_in = nil
+        @cache_store = nil
+      end
+
+      private
+
+      def default_cache_store
+        if defined?(Rails) && Rails.respond_to?(:cache)
+          Rails.cache
+        else
+          raise ConfigurationError, "No cache store configured. Set SitemapGenerator::CacheAdapter.cache_store or use within a Rails application."
+        end
+      end
+    end
+
+    # Error raised when the adapter is misconfigured
+    class ConfigurationError < StandardError; end
+
+    # Initialize a new CacheAdapter.
+    #
+    # @param cache_key_prefix [String] Prefix for cache keys (default: "sitemap_generator")
+    # @param expires_in [Integer, ActiveSupport::Duration] Cache expiration time (default: 24.hours)
+    # @param cache_store [#fetch, #read, #write] Cache store to use (default: Rails.cache)
+    #
+    # @example
+    #   adapter = SitemapGenerator::CacheAdapter.new(
+    #     cache_key_prefix: "myapp:sitemap",
+    #     expires_in: 12.hours
+    #   )
+    def initialize(cache_key_prefix: nil, expires_in: nil, cache_store: nil)
+      self.class.cache_key_prefix = cache_key_prefix if cache_key_prefix
+      self.class.expires_in = expires_in if expires_in
+      self.class.cache_store = cache_store if cache_store
+    end
+
+    # Write sitemap data to the cache.
+    #
+    # This method is called by SitemapGenerator when creating sitemaps.
+    # It conforms to the adapter interface expected by sitemap_generator.
+    #
+    # @param location [SitemapGenerator::SitemapLocation] Location object with filename info
+    # @param raw_data [String] The raw XML sitemap data
+    # @return [void]
+    def write(location, raw_data)
+      cache_key = "#{self.class.cache_key_prefix}:#{location.filename}"
+
+      self.class.cache_store.write(
+        cache_key,
+        raw_data,
+        expires_in: self.class.expires_in
+      )
+
+      log_write(location.filename, raw_data.bytesize)
+    end
+
+    private
+
+    def log_write(filename, bytesize)
+      if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+        Rails.logger.info "[SitemapGenerator::CacheAdapter] Cached #{filename} (#{bytesize} bytes)"
+      end
+    end
+  end
+end

data/lib/sitemap_generator-cache_adapter.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "sitemap_generator/cache_adapter"

metadata

@@ -0,0 +1,114 @@
+--- !ruby/object:Gem::Specification
+name: sitemap_generator-cache_adapter
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Steve Hill
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-01-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: sitemap_generator
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: |
+  A cache-based storage adapter for the sitemap_generator gem. Stores sitemaps
+  in Rails.cache instead of the filesystem, making it ideal for Kubernetes
+  deployments, Heroku, and other environments with ephemeral or read-only
+  filesystems. Works with any Rails cache backend including Solid Cache,
+  Redis, and Memcached.
+email:
+- steve@stevehill.xyz
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/sitemap_generator-cache_adapter.rb
+- lib/sitemap_generator/cache_adapter.rb
+- lib/sitemap_generator/cache_adapter/version.rb
+homepage: https://github.com/stevehill1981/sitemap_generator-cache_adapter
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/stevehill1981/sitemap_generator-cache_adapter
+  source_code_uri: https://github.com/stevehill1981/sitemap_generator-cache_adapter
+  changelog_uri: https://github.com/stevehill1981/sitemap_generator-cache_adapter/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+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: 3.5.22
+signing_key:
+specification_version: 4
+summary: Cache adapter for sitemap_generator gem
+test_files: []