geminabox 3.1.1 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4da5997cf6f07bf5f5c18308b50ddabae4e3acad3c59b5e725555632c94338ec
-  data.tar.gz: 27a3b1392251204e9f210b9efd1b2dbb0e081e851381fce830385f1eb9db4c28
+  metadata.gz: 758c29c033252b87dc6fbe24ee015340f6f0c365ecc01aed02b7809e15ff3a6e
+  data.tar.gz: 321199cded3cc8b60cf4ecf7f9b04c2a14ec5cc5246a0f072e3d4d12307106cd
 SHA512:
-  metadata.gz: 74b98e66ccc6112d37fb694189c216297cbdfedaeaf1570ce2c0682db24722cb59c1ea5f513f7068743beb7b607969c6eca404f47d72aac822d99a066e9c07be
-  data.tar.gz: 4c818745e2edf7e128e4c6849d07a01f54b29cc851eaa57d5ffb9f101076b28db02f2c45ec49cc8c2bb25500f8e0ad1c67930b54b851122b4041e0f42fac8591
+  metadata.gz: b726d61fe2807fb6c2d0d19544c9e52d8b3cef10be0dd8d772e72f866d286017609034e54ff15ac222cb5bca6fac9394e57b964ae8cb939c7a4e34bc73431f89
+  data.tar.gz: 0d84ea5560b6cc1bd32de94dd0b6952256f820e98ca5fdfbda9656c47eea1fecac25c8f3177518fc6ca59ba2fc293f072f75c18154f69d1e50cb70131208c05a

data/README.md

@@ -4,14 +4,12 @@
 
 [![Ruby](https://github.com/geminabox/geminabox/actions/workflows/ruby.yml/badge.svg)](https://github.com/geminabox/geminabox/actions/workflows/ruby.yml?query=branch%3Amaster)
 [![Gem Version](https://badge.fury.io/rb/geminabox.svg)](http://badge.fury.io/rb/geminabox)
-[![Code Climate](https://codeclimate.com/github/geminabox/geminabox/badges/gpa.svg)](https://codeclimate.com/github/geminabox/geminabox)
-
 Geminabox lets you host your own gems, and push new gems to it just like with rubygems.org.
-The bundler dependencies API is supported out of the box.
+Bundler finds your gems through the [compact index](#compact-index), with no client configuration.
 Authentication is left up to either the web server, or the Rack stack.
-For basic auth, try [Rack::Auth](http://www.rubydoc.info/github/rack/rack/Rack/Auth/Basic).
+For basic auth, try [Rack::Auth::Basic](https://rubydoc.info/gems/rack/Rack/Auth/Basic).
 
-![screen shot](http://pics.tomlea.co.uk/bbbba6/geminabox.png)
+![Geminabox web UI listing hosted gems with install commands](docs/screenshot.png)
 
 ## System Requirements
 
@@ -20,7 +18,10 @@ For basic auth, try [Rack::Auth](http://www.rubydoc.info/github/rack/rack/Rack/A
 
 ## Server Setup
 
-    gem install geminabox
+    gem install geminabox rackup webrick
+
+`rackup` and a Rack server are separate gems on Ruby 3.0+ with Rack 3.
+WEBrick is used here; any Rack server works.
 
 Create a config.ru as follows:
 
@@ -39,63 +40,138 @@ Create a config.ru as follows:
 
     run Geminabox::Server
 
-Start your gem server with 'rackup' to run WEBrick or hook up the config.ru as you normally would ([passenger](https://www.phusionpassenger.com/), [thin](http://code.macournoyer.com/thin/), [unicorn](https://bogomips.org/unicorn/), whatever floats your boat).
-
-## RubyGems Proxy
-
-> **Deprecated.** The RubyGems proxy is unmaintained and **will be removed in
-> Geminabox 4.0.** It depends on the RubyGems.org Dependency API
-> (`/api/v1/dependencies`), which was [sunset on 2023-05-24](https://blog.rubygems.org/2023/02/22/dependency-api-deprecation.html)
-> in favour of the Compact Index API, so proxy mode no longer functions.
-> Enabling it now emits a deprecation warning. Do not rely on this feature.
-
-Geminabox can be configured to pull gems, it does not currently have, from rubygems.org. To enable this mode you can either:
+Start your gem server with `rackup`, or hook up the config.ru as you normally would ([passenger](https://www.phusionpassenger.com/), [puma](https://puma.io/), [unicorn](https://yhbt.net/unicorn/), whatever floats your boat).
 
-Set RUBYGEM_PROXY to true in the environment:
+## Using Geminabox alongside rubygems.org
 
-    RUBYGEMS_PROXY=true rackup
+Geminabox serves only the gems you push to it. To use it together with
+rubygems.org, declare it as a scoped source in your Gemfile so that every gem
+is pinned to exactly one source:
 
-Or in config.ru (before the run command), set:
-
-    Geminabox.rubygems_proxy = true
-
-If you want Geminabox to carry on providing gems when rubygems.org is unavailable, add this to config.ru:
-
-    Geminabox.allow_remote_failure = true
-
-## HTTP adapter
+```ruby
+source "https://rubygems.org"
 
-Geminabox uses the HTTPClient gem to manage its connections to remote resources.
-The relationship is managed via Geminabox::HttpClientAdapter.
+source "https://gems.example.com" do
+  gem "internal-widgets"
+  gem "internal-tools"
+end
+```
 
-To configure options of HTTPClient, pass your own HTTPClient object in config.ru as:
+This pinning is Bundler's protection against dependency confusion: a gem name
+that exists on both servers can never silently resolve to the wrong one.
+
+### RubyGems proxy (removed in 4.0)
+
+Earlier versions of Geminabox could proxy rubygems.org and serve remote and
+local gems from one merged namespace. The feature was deprecated in 3.1.0 and
+removed in 4.0:
+
+- It relied on the RubyGems.org Dependency API
+  (`/api/v1/dependencies`), which was
+  [sunset on 2023-05-24](https://blog.rubygems.org/2023/02/22/dependency-api-deprecation.html),
+  so the proxy had not worked for years.
+- Serving remote and local gems from one namespace invites dependency
+  confusion attacks and defeats Bundler's source pinning described above.
+
+When upgrading, remove `Geminabox.rubygems_proxy` and its related settings
+(`rubygems_proxy_merge_strategy`, `allow_remote_failure`, `ruby_gems_url`,
+`bundler_ruby_gems_url`) from your config.ru, and point your Gemfile at
+rubygems.org directly with a scoped source block as shown above. Leftover
+settings won't break your server: 4.0 warns about each one and ignores it,
+and the `RUBYGEMS_PROXY` and `RUBYGEMS_PROXY_MERGE_STRATEGY` environment
+variables get the same startup warning. These shims go away in 5.0.
+
+If you need a caching or mirroring proxy for rubygems.org (air-gapped
+networks, bandwidth, protection against upstream yanks), use
+[gemstash](https://github.com/rubygems/gemstash), maintained by the RubyGems
+organization.
+
+## Compact index
+
+Geminabox serves the [compact index API](https://guides.rubygems.org/rubygems-org-compact-index-api/)
+(`/versions`, `/info/GEMNAME`, `/names`). Bundler 1.12+ detects and uses it
+automatically; no client configuration is needed. Responses support
+`If-None-Match` and ranged requests, so `bundle install` only downloads
+index data that changed since the last run.
+
+The materialized index lives in `data/compact_index/` and is updated
+whenever gems are added or removed. Deleting that directory (or hitting
+`/reindex`) is safe; it is rebuilt from the stored gems on the next request.
+
+On installs upgraded from an earlier version with many stored gems, the
+first request to `/versions` builds the index and can take a while as it
+checksums every stored gem, so hitting `/reindex` or `/versions` right
+after upgrading avoids surprising the first `bundle install`.
+
+### Running behind a reverse proxy
+
+A stock nginx or Passenger deployment needs no special configuration for the
+compact index. gzip is safe to leave on, even for `text/plain`: Bundler sends
+its ranged requests without `Accept-Encoding`, and nginx never compresses 206
+responses, so 304 revalidation and ranged tail appends keep working.
+
+Two things do interfere:
+
+- Proxy-level caching of `/versions`, `/info/*`, or `/names` (nginx
+  `proxy_cache`, or a CDN). The files reference each other by checksum, so a
+  cache serving one fresh and another stale makes Bundler report checksum
+  mismatches. Bundler already caches and revalidates client-side; leave these
+  paths uncached.
+- Middleware or middleboxes that strip or rewrite headers. Removing `ETag`
+  disables 304 revalidation; removing `Repr-Digest`/`Digest` makes Bundler
+  refuse to append partial responses and re-download the full file after
+  every change.
+
+### Replacing a published version
+
+`gem inabox -o` (and the `allow_replace` server option) overwrites a stored
+gem in place: same version number, different contents. Geminabox updates the
+compact index to match, including the new checksum. Bundler, however, guards
+against a version's bytes changing.
+
+Since 2.5, Bundler records each gem's checksum in the `CHECKSUMS` section of
+`Gemfile.lock`. On a later resolve it compares the checksum the server now
+advertises against the locked one, and if they differ for the same name and
+version it aborts with `Bundler::ChecksumMismatchError`, treating the change as
+a possible supply-chain swap. Nothing on the server can override this; the
+conflict is between the client's lockfile and the replaced contents.
+
+An overwrite is therefore transparent only to consumers who have not locked
+that version yet. Anyone whose `Gemfile.lock` already pins it hits the error on
+their next `bundle install` or `bundle update`. Their options are to remove
+that gem's line from `CHECKSUMS`, delete the lockfile and re-resolve, or turn
+off the check with `bundle config set --local disable_checksum_validation true`.
+The clean fix is to bump the version instead of replacing it; treat `-o` as a
+convenience for a private box whose gems nobody has locked yet.
+
+## HTTP client
+
+The Geminabox server makes no outbound HTTP requests. The `gem inabox`
+client uploads gems with the [HTTPClient](https://github.com/nahi/httpclient)
+gem, which honors the `http_proxy` / `HTTP_PROXY` environment variables.
+
+If you drive `GeminaboxClient` from Ruby (a Rake task, say), you can configure
+its HTTP layer through `Geminabox.http_adapter` before creating the client:
 
 ```ruby
+require "geminabox"
+require "geminabox_client"
+
 # Geminabox.http_adapter = Geminabox::HttpClientAdapter.new # default
-Geminabox.http_adapter.http_client = HTTPClient.new(ENV['http_proxy']).tap do |http_client|
-  http_client.transparent_gzip_decompression = true
+Geminabox.http_adapter.http_client = HTTPClient.new.tap do |http_client|
   http_client.keep_alive_timeout = 32 # sec
-  http_client.ssl_config.verify_mode = OpenSSL::SSL::VERIFY_NONE
-  http_client.send_timeout = 0
-  http_client.receive_timeout = 0
 end
+
+GeminaboxClient.new("https://gems.example.com").push("pkg/my-gem-1.0.0.gem")
 ```
 
-If you would like to use an alternative HTTP gem, create your own adapter
-and specify it in config.ru:
+To use a different HTTP library, subclass `Geminabox::HttpAdapter` and
+implement `post` and `set_auth` (the client's upload path), plus `get` and
+`get_content` for completeness. `Geminabox::TemplateFaradayAdapter` is a
+worked example.
 
     Geminabox.http_adapter = YourHttpAdapter.new
 
-It is recommend (but not essential) that your adapter inherits from HttpAdapter.
-The adapter will need to replace HttpAdapter's methods with those specific to
-the alternative HTTP gem. It should also be able to handle HTTP proxy
-settings.
-
-Defining your own adapter also allows you to configure Geminabox to use the
-local systems SSL certificates.
-
-TemplateFaradayAdapter is provided as an example of an alternative HTTPAdapter.
-
 ## Hooks
 
 You can add a hook (anything callable) which will be called when a gem is
@@ -108,15 +184,15 @@ end
 ```
 
 Typically you might use this to push a notification to your team chat. Any
-exceptions which occur within the hook is silently ignored, so please ensure they
-are handled properly if this is not desirable.
+exceptions raised within the hook are silently ignored, so handle them
+yourself if that is not what you want.
 
 Also, please note that this hook blocks `POST /upload` and `POST /api/v1/gems` APIs processing.
-Hook authors are responsible to perform any action non-blocking/async to avoid HTTP timeout.
+Hook authors are responsible for making slow work non-blocking/async to avoid HTTP timeouts.
 
 ## Client Usage
 
-Since version 0.10, Geminabox supports the standard gemcutter push API:
+Geminabox supports the standard gemcutter push API:
 
     gem push pkg/my-awesome-gem-1.0.gem --host HOST
 
@@ -126,7 +202,7 @@ You can also use the gem plugin:
 
     gem inabox pkg/my-awesome-gem-1.0.gem
 
-And since version 1.2.0, Geminabox supports the standard gemcutter yank API:
+And the standard gemcutter yank API:
 
     gem yank my-awesome-gem -v 1.0 --host HOST
 
@@ -148,15 +224,18 @@ Simples!
         -c, --configure                  Configure GemInABox
         -g, --host HOST                  Host to upload to.
         -o, --overwrite                  Overwrite Gem.
+        -p, --port                       Sets port
 
 
       Common Options:
         -h, --help                       Get help on this command
         -V, --[no-]verbose               Set the verbose level of output
-        -q, --quiet                      Silence commands
+        -q, --quiet                      Silence command progress meter
+            --silent                     Silence RubyGems output
             --config-file FILE           Use this config file instead of default
             --backtrace                  Show stack backtrace on errors
             --debug                      Turn on Ruby debugging
+            --norc                       Avoid loading any .gemrc file
 
 
       Arguments:
@@ -175,11 +254,19 @@ Using Gem in a Box is really simple with the Dockerfile.  Move this Dockerfile i
 That directory only needs to contain:
 
 ```
-config.ru (explained above)
+config.ru
 Gemfile
 Gemfile.lock
 ```
 
+Use the config.ru from [Server Setup](#server-setup), with the data directory
+set to the path the image prepares for it (the container runs as a non-root
+user and cannot create directories elsewhere):
+
+```ruby
+Geminabox.data = "/usr/src/app/data"
+```
+
 Your Gemfile only needs:
 
 ```ruby
@@ -197,15 +284,19 @@ docker build -t geminabox .
 ```
 
 ```
-docker run -d -p 9292:9292 geminabox:latest
+docker run -d -p 9292:9292 -v geminabox-data:/usr/src/app/data geminabox:latest
 ```
 
-Your server should now be running!
+Your server should now be running! The `geminabox-data` volume keeps your
+gems when the container is replaced; without it they are lost.
 
 
 ## Running the tests
 
-Running `rake` will run the complete test suite.
+Running `rake` runs the unit, request, and integration tests.
+`rake test:conformance` runs the RubyGems compact-index conformance suite
+separately. See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full set of checks
+CI runs.
 
 The test suite uses
 [minitest-reporters](https://github.com/minitest-reporters/minitest-reporters)

data/lib/geminabox/compact_index_api.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'digest'
+
+module Geminabox
+  # Sinatra helpers implementing the compact index HTTP semantics:
+  # - ETag is the quoted MD5 of the full body (Bundler <= 2.4 verifies
+  #   exactly that after reassembling ranged fetches).
+  # - A single byte range is honored in all three forms (bytes=N-, bytes=N-M,
+  #   bytes=-N); Bundler only ever sends the open-ended tail. Multipart,
+  #   malformed, and unsatisfiable ranges get a full 200 rather than a 416,
+  #   which clients must tolerate (RFC 9110 permits ignoring Range).
+  # - Repr-Digest/Digest carry sha-256 of the FULL file even on 206 —
+  #   without them Bundler >= 2.5 refuses to append partial responses.
+  #
+  # Requires the including class to provide #dependency_cache.
+  module CompactIndexApi
+    def serve_compact_file(path)
+      halt 404 unless File.file?(path)
+      stat = File.stat(path)
+      contents = File.binread(path)
+      md5, sha256 = compact_file_digests(path, stat, contents)
+      etag = %("#{md5}")
+      headers "ETag" => etag,
+              "Accept-Ranges" => "bytes",
+              "Repr-Digest" => "sha-256=:#{sha256}:",
+              "Digest" => "sha-256=#{sha256}",
+              "Cache-Control" => "max-age=60"
+      content_type "text/plain; charset=utf-8"
+      halt 304 if request.env["HTTP_IF_NONE_MATCH"] == etag
+      range = byte_range(request.env["HTTP_RANGE"], contents.bytesize)
+      if range
+        status 206
+        headers "Content-Range" =>
+          "bytes #{range.begin}-#{range.end}/#{contents.bytesize}"
+        contents.byteslice(range)
+      else
+        contents
+      end
+    end
+
+    private
+
+    # Inclusive byte range to serve, or nil to serve the whole body.
+    def byte_range(header, size)
+      match = /\Abytes=(\d*)-(\d*)\z/.match(header.to_s)
+      return if match.nil? || size.zero?
+
+      first, last = match.captures
+      return suffix_range(last, size) if first.empty?
+
+      first_byte = Integer(first)
+      return if first_byte >= size
+
+      last_byte = last.empty? ? size - 1 : [Integer(last), size - 1].min
+      first_byte..last_byte unless last_byte < first_byte
+    end
+
+    # bytes=-N asks for the final N bytes; N == 0 is unsatisfiable.
+    def suffix_range(last, size)
+      return if last.empty?
+
+      length = Integer(last)
+      return if length.zero?
+
+      [size - length, 0].max..(size - 1)
+    end
+
+    def compact_file_digests(path, stat, contents)
+      key = "compact_digests:#{path}:#{stat.mtime.to_f}:#{stat.size}"
+      dependency_cache.marshal_cache(key) do
+        [Digest::MD5.hexdigest(contents),
+         [Digest::SHA256.digest(contents)].pack("m0")]
+      end
+    end
+  end
+end

data/lib/geminabox/compact_indexer.rb

@@ -0,0 +1,280 @@
+# frozen_string_literal: true
+
+require 'compact_index'
+require 'digest'
+require 'time'
+require 'tempfile'
+require 'tmpdir'
+require 'fileutils'
+require 'rubygems/util'
+
+module Geminabox
+  # Materializes the compact index API bodies (/versions, /info/NAME, /names)
+  # under data/compact_index/, from the gems recorded in the legacy Marshal
+  # specs indexes. Callers must hold the repository lock while writing.
+  #
+  # Invariant: the MD5 in every versions.list line is the MD5 of the exact
+  # bytes of the info/NAME file current when the line was written.
+  class CompactIndexer
+    def initialize(data_dir = Geminabox.data)
+      @data_dir = data_dir
+    end
+
+    def compact_index_dir
+      File.join(@data_dir, "compact_index")
+    end
+
+    def versions_path
+      File.join(compact_index_dir, "versions.list")
+    end
+
+    def names_path
+      File.join(compact_index_dir, "names")
+    end
+
+    def info_path(name)
+      File.join(compact_index_dir, "info", name)
+    end
+
+    def reindex
+      FileUtils.mkdir_p(File.join(compact_index_dir, "info"))
+      known = known_versions
+      current = current_versions
+      if known
+        reconcile(known, current)
+      else
+        full_build(current)
+      end
+    end
+
+    # True when versions.list exists, parses, and records NAME at all --
+    # including a fully-yanked name whose live versions net to zero. Reads
+    # only versions.list and takes no lock, so callers can gate a read-path
+    # heal on it without letting arbitrary /info probes force index writes.
+    def ledger_lists?(name)
+      state, = known_versions
+      !state.nil? && state.key?(name)
+    end
+
+    # Rebuild the single info/NAME file the read path found missing while
+    # versions.list still lists the gem, so a partially corrupted index does
+    # not 404 a gem Bundler was told exists. Renders from the current specs
+    # index, so the bytes -- and their MD5 -- match what a full reconcile
+    # would write; a name with no live versions restores the empty body
+    # reconcile left at yank time. Returns whether it wrote the file; a name
+    # the ledger does not list is left to 404. Callers must hold the
+    # repository lock.
+    def heal_info(name)
+      return false unless ledger_lists?(name)
+
+      versions = current_versions[name]
+      if versions
+        write_info(name, versions)
+      else
+        atomic_write(info_path(name), CompactIndex.info([]))
+      end
+      true
+    end
+
+    private
+
+    # Cumulative state recorded in versions.list. Returns nil when the file
+    # is missing or unparseable, which triggers a from-scratch build.
+    # Otherwise returns [state, checksums]:
+    #   state     => name => array of version_and_platform strings still
+    #                live (yanks subtracted).
+    #   checksums => name => the last MD5 recorded for that name, so a
+    #                content-only change can be detected against it.
+    def known_versions
+      return nil unless File.exist?(versions_path)
+
+      lines = File.read(versions_path).split("\n")
+      separator = lines.index("---")
+      return nil unless separator
+
+      state = Hash.new { |hash, key| hash[key] = [] }
+      checksums = {}
+      lines.drop(separator + 1).each do |line|
+        name, versions, checksum = line.split
+        return nil unless name && versions && checksum
+
+        versions.split(",").each do |entry|
+          if entry.start_with?("-")
+            state[name].delete(entry[1..])
+          else
+            state[name] << entry
+          end
+        end
+        checksums[name] = checksum
+      end
+      [state, checksums]
+    end
+
+    def reconcile(known, current)
+      known_state, known_checksums = known
+      additions = +""
+
+      current.each do |name, versions|
+        current_ids = versions.map(&:number_and_platform)
+        added = current_ids - known_state.fetch(name, [])
+        removed = known_state.fetch(name, []) - current_ids
+        if added.empty? && removed.empty?
+          line = refresh_line(name, versions, current_ids, known_checksums[name])
+          additions << line if line
+          next
+        end
+        info_body = write_info(name, versions)
+        entries = added + removed.map { |id| "-#{id}" }
+        additions << version_line(name, entries, info_body)
+      end
+
+      (known_state.keys - current.keys).each do |name|
+        removed = known_state[name]
+        next if removed.empty?
+
+        info_body = CompactIndex.info([])
+        atomic_write(info_path(name), info_body)
+        additions << version_line(name, removed.map { |id| "-#{id}" }, info_body)
+      end
+
+      if additions.empty?
+        # Self-heal a names file deleted out from under an intact
+        # versions.list, so /names does not 404 forever.
+        write_names(current.keys) unless File.exist?(names_path)
+        return
+      end
+      atomic_write(versions_path, File.read(versions_path) + additions)
+      write_names(current.keys)
+    end
+
+    # A same-version replacement (allow_replace / `gem inabox -o`) changes the
+    # .gem contents without changing the version identity set, so the identity
+    # diff is empty. Detect that here and, when the freshly rendered info body
+    # differs from what versions.list last recorded, emit a "touch" line that
+    # yanks and re-adds every current version in one entry. Bundler processes
+    # entries in order, so delete-then-add leaves the version set intact while
+    # the trailing MD5 (last checksum wins) points at the new info bytes.
+    # Returns nil when nothing needs to change, keeping reconcile idempotent.
+    def refresh_line(name, versions, current_ids, known_checksum)
+      return unless dirty?(name, versions)
+
+      info_body = write_info(name, versions)
+      return if Digest::MD5.hexdigest(info_body) == known_checksum
+
+      entries = current_ids.map { |id| "-#{id}" } + current_ids
+      version_line(name, entries, info_body)
+    end
+
+    # A gem is content-dirty when its info file is missing, or when any of its
+    # stored .gem files is at least as new as the info file. The >= tolerance
+    # matches Geminabox::Indexer.updated_gemspecs.
+    def dirty?(name, versions)
+      info = info_path(name)
+      return true unless File.exist?(info)
+
+      info_mtime = File.stat(info).mtime
+      versions.any? do |version|
+        gem_file = File.join(@data_dir, "gems", "#{version.gemfile_name}.gem")
+        File.exist?(gem_file) && File.stat(gem_file).mtime >= info_mtime
+      end
+    end
+
+    def version_line(name, entries, info_body)
+      "#{name} #{entries.join(',')} #{Digest::MD5.hexdigest(info_body)}\n"
+    end
+
+    # name => GemVersionCollection, name-sorted; versions version-sorted.
+    def current_versions
+      GemVersionCollection.from_specs_index(@data_dir).by_name.to_h
+    end
+
+    def full_build(current)
+      gems = current.map do |name, versions|
+        info_body = write_info(name, versions)
+        light_versions = versions.map do |version|
+          CompactIndex::GemVersion.new(version.number.to_s, version.platform,
+                                       nil, Digest::MD5.hexdigest(info_body))
+        end
+        CompactIndex::Gem.new(name, light_versions)
+      end
+      write_versions_list(gems)
+      write_names(current.keys)
+    end
+
+    def write_versions_list(gems)
+      # VersionsFile#create writes in place; render to a temp path and
+      # publish atomically like every other file we serve.
+      Dir.mktmpdir("compact", @data_dir) do |dir|
+        tmp_path = File.join(dir, "versions.list")
+        CompactIndex::VersionsFile.new(tmp_path).create(gems, Time.now.utc.iso8601)
+        atomic_write(versions_path, File.read(tmp_path))
+      end
+    end
+
+    # Renders and writes info/NAME; returns the exact bytes written so
+    # callers can hash them for the corresponding versions.list line.
+    def write_info(name, versions)
+      body = CompactIndex.info(info_versions(versions))
+      atomic_write(info_path(name), body)
+      body
+    end
+
+    def write_names(names)
+      atomic_write(names_path, CompactIndex.names(names.sort))
+    end
+
+    def info_versions(versions)
+      versions.map do |version|
+        spec = load_spec(version)
+        next unless spec
+
+        CompactIndex::GemVersion.new(
+          version.number.to_s,
+          version.platform,
+          gem_checksum(version),
+          nil,
+          info_dependencies(spec),
+          requirement_string(spec.required_ruby_version),
+          requirement_string(spec.required_rubygems_version)
+        )
+      end.compact
+    end
+
+    def info_dependencies(spec)
+      spec.dependencies
+          .select { |dep| dep.type == :runtime }
+          .map { |dep| [dep.name.is_a?(Array) ? dep.name.first : dep.name, dep.requirement.to_s] }
+          .sort_by(&:first)
+          .map { |name, requirement| CompactIndex::Dependency.new(name, requirement, nil, nil) }
+    end
+
+    def requirement_string(requirement)
+      requirement&.to_s
+    end
+
+    def load_spec(version)
+      spec_file = File.join(@data_dir, "quick", "Marshal.#{Gem.marshal_version}",
+                            "#{version.gemfile_name}.gemspec.rz")
+      return unless File.exist?(spec_file)
+
+      Marshal.load(Gem::Util.inflate(Gem.read_binary(spec_file)))
+    end
+
+    def gem_checksum(version)
+      Digest::SHA256.file(File.join(@data_dir, "gems", "#{version.gemfile_name}.gem")).hexdigest
+    end
+
+    def atomic_write(file_name, contents)
+      temp_file = Tempfile.new(".compact", compact_index_dir)
+      temp_file.binmode
+      temp_file.write(contents)
+      # Tempfile is created 0600; publish the served files world-readable
+      # (subject to the process umask) like Gem::Indexer's own output.
+      # chmod while the handle is still open -- Tempfile#chmod delegates to
+      # the underlying File, which raises once closed.
+      temp_file.chmod(0o644 & ~File.umask)
+      temp_file.close
+      File.rename(temp_file.path, file_name)
+    end
+  end
+end

data/lib/geminabox/gem_version.rb

@@ -37,6 +37,14 @@ module Geminabox
       included_platform = ruby? ? nil : platform
       [name, number, included_platform].compact.join('-')
     end
+
+    def number_and_platform
+      if platform.nil? || ruby?
+        number.to_s
+      else
+        "#{number}-#{platform}"
+      end
+    end
   end
 
 end