indexmap 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ef452a5928b87f84f65ecb9ba2afcab5340d9d09c5d8c8dfd8c4ffb3217a68fd
-  data.tar.gz: 03b11e1d9360bbd797d6b61886c99d1619247877dfd2c4676efeca9a1119764c
+  metadata.gz: 90b723b27367659107827ca3ff1f7473c6a4a917b62ae1cdb4ae2cfcf440f3f2
+  data.tar.gz: cd5be4391a83b1378efcad593408648822dabff4dc8e5479e6ae3e3c12d93ac3
 SHA512:
-  metadata.gz: a04a772029e2438636df90b65004a27c54e1cf3360205fd556feff615768fd527668fe2a3e3063f2831b9af9afb4edd983e48e73b922278c4c10a63d936b938e
-  data.tar.gz: 6ce68d9ee6343aaf7c4bbff6860a712d743899390b4a8a3a09c712694c95cff32cc0acd85f30a43e2ba37f0c8ff671d2af11028e63976649ae90e5100d5e0a1b
+  metadata.gz: '099bf5472fae8a8be3d17ad40003ea5802dd410799431af367e604dca3cd0fce04e98555526dfb36b98f270774b41eec160a47c5abdc9fd81ac148080901d96f'
+  data.tar.gz: e53e45fe051e02b0000e05c5000f8f23c2e1cc7ab78a952cad6a4a33891b108c8811cd67d9fcadea6cf39bea4abf74eae9736d9e85402e6a1988ef49ace9c0dc

data/CHANGELOG.md

@@ -5,14 +5,12 @@ 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).
 
-## [0.6.0] - 2026-05-01
+## [0.7.0] - 2026-05-08
 
 
-### Added
+### Fixed
 
-- add the url count to google ping output (#9)
-
-- support named sitemap outputs (#10)
+- avoid rewriting existing IndexNow key files (#11)
 
 
 

data/README.md

@@ -34,6 +34,10 @@ Or install it directly:
 gem install indexmap
 ```
 
+Upgrading an existing app? Read [UPGRADE.md](UPGRADE.md) before deploying,
+especially if the app uses custom storage or stores sitemap files under a
+directory prefix such as `sitemaps/`.
+
 ## Ruby Usage
 
 ```ruby
@@ -51,7 +55,6 @@ sections = [
 
 Indexmap::Writer.new(
   sections: sections,
-  public_path: Pathname("public"),
   base_url: "https://example.com"
 ).write
 ```
@@ -63,7 +66,12 @@ In an initializer:
 ```ruby
 Indexmap.configure do |config|
   config.base_url = -> { "https://example.com" }
-  config.public_path = -> { Rails.public_path }
+  config.storage = -> do
+    Indexmap::Storage::Filesystem.new(
+      path: Rails.public_path,
+      public_url: config.base_url
+    )
+  end
   config.sections = -> do
     [
       Indexmap::Section.new(
@@ -85,26 +93,26 @@ bin/rails indexmap:sitemap:format
 bin/rails indexmap:sitemap:validate
 ```
 
-`indexmap:sitemap:create` is the main task. It writes sitemap files to a local
-temporary directory, formats them, validates the result, then replaces the final
-XML files. Existing sitemap files are left untouched if generation or validation
-fails.
+`indexmap:sitemap:create` is the main task. It builds sitemap files in memory,
+formats them, validates the result, then writes the final XML files to the
+configured storage. Existing sitemap files are left untouched if generation or
+validation fails.
 
 ### Default Index Mode
 
 This is the default behavior. `indexmap` writes:
 
-- `public/sitemap.xml` as a sitemap index
+- `sitemap.xml` as a sitemap index
 - one or more child sitemap files from `config.sections`
 
 ### Single-File Mode
 
-For sites that only want one `public/sitemap.xml` file:
+For sites that only want one `sitemap.xml` file:
 
 ```ruby
 Indexmap.configure do |config|
   config.base_url = -> { "https://example.com" }
-  config.public_path = -> { Rails.public_path }
+  config.storage = -> { Indexmap::Storage::Filesystem.new(path: Rails.public_path, public_url: config.base_url) }
   config.format = :single_file
   config.entries = -> do
     [
@@ -122,13 +130,12 @@ In `:single_file` mode, `indexmap` writes a `urlset` directly to `sitemap.xml` a
 Most apps only need the default output. Use named outputs when one part of the
 sitemap must be generated separately, for example when static pages can be
 generated during deploy but database-heavy pages should refresh later. Named
-outputs still write normal sitemap XML files to a filesystem path; storage and
-serving are application concerns.
+outputs write through the same configured storage as the default output.
 
 ```ruby
 Indexmap.configure do |config|
   config.base_url = -> { "https://example.com" }
-  config.public_path = -> { Rails.root.join("storage/sitemaps") }
+  config.storage = -> { Indexmap::Storage::Filesystem.new(path: Rails.root.join("storage/sitemaps"), public_url: config.base_url) }
   config.sections = -> { Sitemap.sections }
 
   config.output :insights_data do |output|
@@ -151,12 +158,57 @@ Generate only the named output:
 Indexmap.create(:insights_data)
 ```
 
-Named outputs inherit `base_url`, `public_path`, and `format` from the main
-configuration unless you override them.
+Named outputs inherit `base_url` and `format` from the main configuration unless
+you override them. Storage is configured once and shared by every output.
+
+`Indexmap.create` uses the same safe publish flow as the rake task: build,
+format, validate, and then write the final XML file or files to storage.
+
+### Storage
+
+Every `indexmap` operation reads and writes through `config.storage`. The storage
+object is the source of truth for generation, validation, parsing, Google
+submission, IndexNow submission, and IndexNow verification files.
+
+The filesystem adapter stores files in a directory and exposes public URLs from
+the same filenames:
+
+```ruby
+Indexmap.configure do |config|
+  config.base_url = "https://example.com"
+  config.storage = Indexmap::Storage::Filesystem.new(
+    path: Rails.public_path,
+    public_url: "https://example.com"
+  )
+end
+```
+
+Rails apps that store sitemap files in Active Storage can use the optional
+adapter. `indexmap` does not depend on `activestorage`; this adapter only uses
+the model and attachment object you pass in.
+
+```ruby
+Indexmap.configure do |config|
+  config.base_url = "https://example.com"
+  config.storage = Indexmap::Storage::ActiveStorage.new(
+    model: SitemapArtifact,
+    filename_column: :filename,
+    attachment: :file,
+    public_url: "https://example.com"
+  )
+end
+```
+
+Custom storage backends can implement the same small interface:
 
-`Indexmap.create` uses the same safe local publish flow as the rake task:
-generate in a temporary directory, format, validate, and then replace the final
-XML file or files.
+```ruby
+storage.write(filename, body, content_type:)
+storage.read(filename)
+storage.exist?(filename)
+storage.list(prefix:, suffix:)
+storage.delete(filename)
+storage.public_url(filename)
+```
 
 ### Deferred Dynamic Sections
 
@@ -168,7 +220,7 @@ replaced successfully.
 ```ruby
 Indexmap.configure do |config|
   config.base_url = -> { "https://example.com" }
-  config.public_path = -> { Rails.root.join("storage/sitemaps") }
+  config.storage = -> { Indexmap::Storage::Filesystem.new(path: Rails.root.join("storage/sitemaps"), public_url: config.base_url) }
   config.sections = -> { Sitemap.sections }
 
   config.output :insights_data do |output|
@@ -201,7 +253,7 @@ while database-dependent output is refreshed by the job backend.
 `indexmap` also includes small utilities for working with generated sitemap files:
 
 ```ruby
-parser = Indexmap::Parser.new(path: Rails.public_path.join("sitemap.xml"))
+parser = Indexmap::Parser.new(source: "sitemap.xml")
 parser.paths
 # => ["/", "/about", "/articles/example"]
 
@@ -263,7 +315,7 @@ If `config.google.property` is not set, `indexmap` defaults to `sc-domain:<host>
 IndexNow submission requires a key. `indexmap` supports two ways to provide it:
 
 - set `config.index_now.key`
-- or keep a valid verification file at `public/<key>.txt`
+- or keep a valid verification file in the configured storage as `<key>.txt`
 
 Configured-key example:
 
@@ -273,7 +325,25 @@ Indexmap.configure do |config|
 end
 ```
 
-If `config.index_now.key` is set, `indexmap:sitemap:create` also writes the matching `public/<key>.txt` verification file automatically.
+If `config.index_now.key` is set, `indexmap:sitemap:create` also ensures the matching `<key>.txt` verification file exists in storage. It leaves an existing valid key file unchanged.
+
+If you need a non-standard verification filename, configure it explicitly:
+
+```ruby
+Indexmap.configure do |config|
+  config.index_now.key = -> { ENV["INDEXNOW_KEY"] }
+  config.index_now.key_filename = -> { "#{ENV.fetch("INDEXNOW_KEY")}.txt" }
+end
+```
+
+You can also disable automatic key-file writes entirely:
+
+```ruby
+Indexmap.configure do |config|
+  config.index_now.key = -> { ENV["INDEXNOW_KEY"] }
+  config.index_now.write_key_file = false
+end
+```
 
 If you prefer the file-based flow, run:
 
@@ -284,7 +354,7 @@ bin/rails indexmap:index_now:write_key
 That task:
 
 - reuses an existing valid key file when present
-- otherwise generates a new key in `public/<key>.txt`
+- otherwise generates a new key in `<key>.txt`
 - makes that key available to `indexmap:index_now:ping` without adding `config.index_now.key`
 
 If neither a configured key nor a valid key file is present, `indexmap:index_now:ping` skips IndexNow submission.

data/lib/indexmap/configuration.rb

@@ -4,7 +4,7 @@ module Indexmap
   class Configuration
     VALID_FORMATS = %i[index single_file].freeze
 
-    attr_writer :base_url, :entries, :format, :index_filename, :public_path, :sections
+    attr_writer :base_url, :entries, :format, :index_filename, :sections, :storage
 
     def initialize
       @format = :index
@@ -38,11 +38,8 @@ module Indexmap
       @index_now ||= IndexNowConfiguration.new
     end
 
-    def public_path
-      value = resolve(@public_path)
-      return Pathname("public") if value.nil?
-
-      Pathname(value)
+    def storage
+      resolve(@storage) || Storage::Filesystem.new(path: "public", public_url: base_url)
     end
 
     def sections

data/lib/indexmap/creator.rb

@@ -1,74 +1,61 @@
 # frozen_string_literal: true
 
 require "nokogiri"
-require "tmpdir"
 
 module Indexmap
   class Creator
-    ValidationConfiguration = Struct.new(:base_url, keyword_init: true)
+    ValidationConfiguration = Struct.new(:base_url, :index_filename, :storage, keyword_init: true)
 
     def initialize(output:)
       @output = output
     end
 
     def create
-      FileUtils.mkdir_p(output.public_path.dirname)
-
-      Dir.mktmpdir("indexmap", output.public_path.dirname) do |dir|
-        staging_path = Pathname(dir)
-        written_files = write_to(staging_path)
-        sitemap_files = sitemap_files_in(staging_path)
-
-        format(sitemap_files)
-        validate(staging_path.join(output.index_filename))
-
-        publish(sitemap_files)
-        written_files.map { |path| output.public_path.join(path.basename) }
-      end
+      files = format(write)
+      validate(files)
+      publish(files)
+      files.map(&:filename)
     end
 
     private
 
     attr_reader :output
 
-    def write_to(staging_path)
-      output.writer.tap do |writer|
-        writer.public_path = staging_path
-      end.write
-    end
-
-    def sitemap_files_in(path)
-      path.glob("sitemap*.xml").sort
+    def write
+      output.writer.write
     end
 
     def format(files)
-      files.each do |file_path|
+      files.map do |file|
         document = Nokogiri::XML(
-          file_path.read,
+          file.body,
           nil,
           nil,
           Nokogiri::XML::ParseOptions::DEFAULT_XML | Nokogiri::XML::ParseOptions::NOBLANKS
         )
         save_options = Nokogiri::XML::Node::SaveOptions::FORMAT | Nokogiri::XML::Node::SaveOptions::AS_XML
 
-        file_path.write(document.to_xml(indent: 2, save_with: save_options))
+        Storage::File.new(
+          filename: file.filename,
+          body: document.to_xml(indent: 2, save_with: save_options),
+          content_type: file.content_type
+        )
       end
     end
 
-    def validate(index_path)
+    def validate(files)
       Validator.new(
-        configuration: ValidationConfiguration.new(base_url: output.base_url),
-        path: index_path
+        configuration: ValidationConfiguration.new(
+          base_url: output.base_url,
+          index_filename: output.index_filename,
+          storage: Storage::Memory.new(files)
+        )
       ).validate!
     end
 
     def publish(files)
-      FileUtils.mkdir_p(output.public_path)
-
-      files.map do |file_path|
-        final_path = output.public_path.join(file_path.basename)
-        File.rename(file_path, final_path)
-        final_path
+      files.each do |file|
+        output.storage.write(file.filename, file.body, content_type: file.content_type)
       end
     end
   end

data/lib/indexmap/index_now_configuration.rb

@@ -5,7 +5,7 @@ module Indexmap
     DEFAULT_ENDPOINT = "https://api.indexnow.org"
     DEFAULT_MAX_URLS_PER_REQUEST = 500
 
-    attr_writer :dry_run, :endpoint, :key, :key_path, :max_urls_per_request
+    attr_writer :dry_run, :endpoint, :key, :key_filename, :max_urls_per_request, :write_key_file
 
     def dry_run?
       value = resolve(@dry_run)
@@ -21,12 +21,19 @@ module Indexmap
       resolve(@key)
     end
 
-    def key_path(public_path:, key: self.key)
-      configured_path = resolve(@key_path)
-      return Pathname(configured_path) unless configured_path.to_s.strip.empty?
+    def write_key_file?
+      value = resolve(@write_key_file)
+      return !key.to_s.strip.empty? if value.nil?
+
+      value == true || value.to_s == "1"
+    end
+
+    def key_filename(key: self.key)
+      configured_filename = resolve(@key_filename)
+      return configured_filename unless configured_filename.to_s.strip.empty?
       return if key.to_s.strip.empty?
 
-      Pathname(public_path).join("#{key}.txt")
+      "#{key}.txt"
     end
 
     def max_urls_per_request

data/lib/indexmap/output.rb

@@ -4,7 +4,7 @@ module Indexmap
   class Output
     VALID_FORMATS = %i[index single_file].freeze
 
-    attr_writer :base_url, :entries, :format, :index_filename, :public_path, :sections
+    attr_writer :base_url, :entries, :format, :index_filename, :sections
 
     def initialize(configuration:)
       @configuration = configuration
@@ -29,9 +29,8 @@ module Indexmap
       resolve(@index_filename) || configuration.index_filename
     end
 
-    def public_path
-      value = resolve(@public_path) || configuration.public_path
-      Pathname(value)
+    def storage
+      configuration.storage
     end
 
     def sections
@@ -57,7 +56,6 @@ module Indexmap
         entries: entries,
         format: format,
         sections: sections,
-        public_path: public_path,
         base_url: base_url,
         index_filename: index_filename
       )

data/lib/indexmap/parser.rb

@@ -8,11 +8,11 @@ module Indexmap
   class Parser
     Entry = Struct.new(:loc, :lastmod, :source_sitemap, keyword_init: true)
 
-    def initialize(path: default_path, rebase_remote_children: false, index_filename: Indexmap.configuration.index_filename, public_path: Indexmap.configuration.public_path)
-      @source = path.to_s
+    def initialize(source: nil, rebase_remote_children: false, index_filename: Indexmap.configuration.index_filename, storage: Indexmap.configuration.storage)
+      @source = (source || index_filename).to_s
       @rebase_remote_children = rebase_remote_children
       @index_filename = index_filename
-      @public_path = public_path
+      @storage = storage
     end
 
     def entries(reset: false)
@@ -58,11 +58,7 @@ module Indexmap
 
     private
 
-    attr_reader :index_filename, :public_path
-
-    def default_path
-      Indexmap::Path.existing_public_path(public_path: public_path, index_filename: index_filename)
-    end
+    attr_reader :index_filename, :storage
 
     def parse_source(source, visited:)
       normalized_source = normalize_source(source)
@@ -105,12 +101,21 @@ module Indexmap
         end
       elsif remote_source?(loc)
         uri = URI.parse(loc)
-        File.join(File.dirname(parent_source), File.basename(uri.path))
+        normalize_local_source(uri.path)
       else
-        File.expand_path(loc, File.dirname(parent_source))
+        resolve_local_child_sitemap(parent_source, loc)
       end
     rescue URI::InvalidURIError
-      File.expand_path(loc, File.dirname(parent_source))
+      resolve_local_child_sitemap(parent_source, loc)
+    end
+
+    def resolve_local_child_sitemap(parent_source, loc)
+      if loc.start_with?("/")
+        normalize_local_source(loc)
+      else
+        parent_directory = File.dirname(parent_source)
+        normalize_local_source((parent_directory == ".") ? loc : File.join(parent_directory, loc))
+      end
     end
 
     def remote_child_source(parent_uri, loc)
@@ -130,12 +135,19 @@ module Indexmap
       if remote_source?(source)
         URI.parse(source).to_s
       else
-        Pathname(source).expand_path.to_s
+        normalize_local_source(source)
       end
     rescue URI::InvalidURIError
       nil
     end
 
+    def normalize_local_source(source)
+      normalized = Pathname(source.to_s).cleanpath.to_s.sub(%r{\A/+}, "")
+      return if normalized.empty? || normalized == ".." || normalized.start_with?("../")
+
+      normalized
+    end
+
     def remote_source?(value)
       uri = URI.parse(value.to_s)
       uri.is_a?(URI::HTTP) || uri.is_a?(URI::HTTPS)
@@ -146,8 +158,8 @@ module Indexmap
     def read_source(source)
       if remote_source?(source)
         fetch_remote_source(source)
-      elsif File.exist?(source)
-        File.read(source, encoding: "UTF-8")
+      elsif storage.exist?(source)
+        storage.read(source)
       end
     end
 

data/lib/indexmap/pinger/base.rb

@@ -46,8 +46,12 @@ module Indexmap
         hostname.sub(/\Awww\./, "")
       end
 
+      def storage
+        configuration.storage
+      end
+
       def sitemap_files
-        Dir.glob(configuration.public_path.join("sitemap*.xml")).sort
+        storage.list(prefix: "sitemap", suffix: ".xml")
       end
 
       def ping_sitemap(_sitemap_file)

data/lib/indexmap/pinger/google.rb

@@ -36,7 +36,7 @@ module Indexmap
       end
 
       def ping_sitemap(sitemap_file)
-        sitemap_url = URI.join(host, File.basename(sitemap_file)).to_s
+        sitemap_url = storage.public_url(sitemap_file)
 
         unless authorized?
           logger.debug("Google Search Console does not have access to the site: #{root_domain}")
@@ -93,7 +93,7 @@ module Indexmap
 
       def sitemap_url_count(files)
         files.each_with_object(Set.new) do |sitemap_file, urls|
-          Parser.new(path: sitemap_file).entries.each do |entry|
+          Parser.new(source: sitemap_file, storage: storage).entries.each do |entry|
             loc = entry.loc.to_s.strip
             urls.add(loc) unless loc.empty?
           end

data/lib/indexmap/pinger/index_now.rb

@@ -42,14 +42,15 @@ module Indexmap
         summarize_results(results)
       end
 
-      def write_key_file(key: index_now_configuration.key, path: nil)
+      def write_key_file(key: index_now_configuration.key, filename: nil)
         key = normalized_configured_key(key)
         return if key.empty?
 
-        path ||= index_now_configuration.key_path(public_path: configuration.public_path, key: key)
-        FileUtils.mkdir_p(path.dirname)
-        File.write(path, key)
-        path
+        filename ||= index_now_configuration.key_filename(key: key)
+        return filename if valid_key_file?(filename)
+
+        storage.write(filename, key, content_type: "text/plain")
+        filename
       end
 
       def ensure_key_file
@@ -60,7 +61,7 @@ module Indexmap
         return existing_path if existing_path
 
         key = generated_key
-        write_key_file(key: key, path: configuration.public_path.join("#{key}.txt"))
+        write_key_file(key: key, filename: "#{key}.txt")
       end
 
       private
@@ -75,7 +76,7 @@ module Indexmap
         files = super
         return files if files.one?
 
-        child_files = files.reject { |file| File.basename(file) == configuration.index_filename }
+        child_files = files.reject { |file| file == configuration.index_filename }
         child_files.empty? ? files : child_files
       end
 
@@ -95,7 +96,7 @@ module Indexmap
 
       def current_entries
         sitemap_files.each_with_object({}) do |sitemap_file, entries|
-          Parser.new(path: sitemap_file).entries.each do |entry|
+          Parser.new(source: sitemap_file, storage: storage).entries.each do |entry|
             next if entry.loc.to_s.strip.empty?
 
             entries[entry.loc] = entry
@@ -177,36 +178,32 @@ module Indexmap
         configured_key = normalized_configured_key(index_now_configuration.key)
         return configured_key unless configured_key.empty?
 
-        existing_key_file&.read
+        storage.read(existing_key_file) if existing_key_file
       end
 
       def existing_key_file
-        configured_path = index_now_configuration.key_path(public_path: configuration.public_path)
-        return configured_path if valid_key_file?(configured_path)
+        configured_filename = index_now_configuration.key_filename
+        return configured_filename if valid_key_file?(configured_filename)
 
-        configuration.public_path.glob("*.txt").sort.find { |file| valid_key_file?(file) }
+        storage.list(suffix: ".txt").find { |filename| valid_key_file?(filename) }
       end
 
       def key_location(api_key:)
-        path = index_now_configuration.key_path(public_path: configuration.public_path, key: api_key) || existing_key_file
-        return unless path
-
-        public_path = configuration.public_path.expand_path
-        key_path = path.expand_path
-        relative_path = key_path.relative_path_from(public_path)
+        filename = index_now_configuration.key_filename(key: api_key) || existing_key_file
+        return unless filename
 
-        URI.join("#{host}/", relative_path.to_s).to_s
+        storage.public_url(filename)
       rescue ArgumentError
         nil
       end
 
-      def valid_key_file?(path)
-        return false unless path&.file?
+      def valid_key_file?(filename)
+        return false unless filename && storage.exist?(filename)
 
-        filename = path.basename(".txt").to_s
-        return false unless filename.match?(KEY_FORMAT)
+        key = File.basename(filename, ".txt").to_s
+        return false unless key.match?(KEY_FORMAT)
 
-        path.read == filename
+        storage.read(filename) == key
       end
 
       def generated_key