Fetch terrain tiles concurrently with persistent connections

Serial fetches (no connection reuse) measured ~650ms/tile, almost all
TCP+TLS handshake — a real bbox at z0..15 is tens of thousands of
tiles, so this was hours for a modest region. Now: 16 worker threads
share a queue (I/O-bound, so the GVL doesn't get in the way), each
keeping its own persistent connection across every tile it fetches.
Measured live against the real Terrarium source: ~40ms/tile, ~16x
faster.

write_terrarium_mbtiles's SQLite writes and progress updates stay on
one thread (draining a results Queue the workers feed), so nothing
needed its own locking beyond the two Queues themselves.

lib/maptool/pmtiles_builder.rb

@@ -28,6 +28,13 @@ module Maptool
     # source's own online maxzoom.
     TERRARIUM_URL_TEMPLATE = "https://s3.amazonaws.com/elevation-tiles-prod/terrarium/%<z>d/%<x>d/%<y>d.png"
     TERRAIN_MAX_ZOOM = 15
+    # A real bbox at z0..15 is tens of thousands of tiles — serial fetches
+    # (the original ponytail'd version of this) measured ~0.65s/tile, almost
+    # all TCP+TLS handshake, no connection reuse: hours for a modest region.
+    # This many workers, each keeping its own persistent connection (see
+    # fetch_terrarium_tile), is a big enough win to matter without looking
+    # like abuse against a public bucket.
+    CONCURRENT_TILE_FETCHES = 16
 
     OFFLINE_STATUS = { state: "idle" }
     TERRAIN_STATUS = { state: "idle" }
@@ -141,10 +148,11 @@ module Maptool
     # public Terrarium-encoded PMTiles archive is known to exist to
     # `extract` from the way offline.pmtiles does above.
     #
-    # ponytail: fetches tiles one at a time, serially — fine for a
-    # park-sized region, slow for a big one. Add a small bounded-concurrency
-    # fetch pool if regenerating a large area turns out to matter in
-    # practice.
+    # fetch_tile.call happens on CONCURRENT_TILE_FETCHES worker threads at
+    # once (I/O-bound — Ruby's GVL is released while a thread blocks on
+    # network I/O, so this genuinely overlaps); every SQLite write and
+    # progress update stays on this thread, draining a results Queue the
+    # workers feed, so nothing here needs its own locking.
     def self.write_terrarium_mbtiles(path, south, west, north, east, fetch_tile, progress)
       db = SQLite3::Database.new(path)
       db.execute_batch(<<~SQL)
@@ -157,29 +165,48 @@ module Maptool
       end
 
       # tile_range per zoom computed once upfront (cheap — no fetching, just
-      # tile math) and reused below, so progress can report a real total
-      # from the very first call instead of only once the run finishes.
-      by_zoom = (0..TERRAIN_MAX_ZOOM).map { |z| [z, tile_range(z, south, west, north, east)] }
-      total = by_zoom.sum { |_z, tiles| tiles.size }
+      # tile math), so progress can report a real total from the very first
+      # call instead of only once the run finishes.
+      work = (0..TERRAIN_MAX_ZOOM).flat_map { |z| tile_range(z, south, west, north, east).map { |x, y| [z, x, y] } }
+      total = work.size
       done = 0
       progress.call(done, total)
 
-      by_zoom.each do |z, tiles|
-        tiles.each do |x, y|
-          bytes = fetch_tile.call(z, x, y)
-          done += 1
-          progress.call(done, total)
-          next unless bytes
+      queue = Queue.new
+      work.each { |item| queue << item }
+      CONCURRENT_TILE_FETCHES.times { queue << nil } # one stop signal per worker
 
-          # MBTiles uses TMS row numbering (0 at the south) — the opposite
-          # of the XYZ scheme both the Terrarium source and this app's own
-          # online raster-dem layer use (0 at the north) — flipped here so
-          # go-pmtiles ends up serving the same tile at the same z/x/y this
-          # app already requests online.
-          tms_y = (2**z) - 1 - y
-          db.execute("INSERT OR REPLACE INTO tiles (zoom_level, tile_column, tile_row, tile_data) VALUES (?, ?, ?, ?)", [z, x, tms_y, bytes.b])
+      results = Queue.new
+      workers = CONCURRENT_TILE_FETCHES.times.map do
+        Thread.new do
+          while (item = queue.pop)
+            z, x, y = item
+            results << [z, x, y, fetch_tile.call(z, x, y)]
+          end
+        ensure
+          # Only set when fetch_tile is fetch_terrarium_tile (a test fake
+          # has no reason to touch this) — closes this worker's persistent
+          # connection rather than leaving the socket for GC to eventually
+          # notice.
+          Thread.current[:maptool_terrarium_http]&.finish
         end
       end
+
+      total.times do
+        z, x, y, bytes = results.pop
+        done += 1
+        progress.call(done, total)
+        next unless bytes
+
+        # MBTiles uses TMS row numbering (0 at the south) — the opposite of
+        # the XYZ scheme both the Terrarium source and this app's own online
+        # raster-dem layer use (0 at the north) — flipped here so go-pmtiles
+        # ends up serving the same tile at the same z/x/y this app already
+        # requests online.
+        tms_y = (2**z) - 1 - y
+        db.execute("INSERT OR REPLACE INTO tiles (zoom_level, tile_column, tile_row, tile_data) VALUES (?, ?, ?, ?)", [z, x, tms_y, bytes.b])
+      end
+      workers.each(&:join)
     ensure
       db&.close
     end
@@ -204,8 +231,14 @@ module Maptool
     end
     private_class_method :lat_to_tile_y
 
+    # One persistent connection per calling Thread (each of
+    # write_terrarium_mbtiles' worker threads calls this many times) instead
+    # of Net::HTTP.get_response's usual "new TCP+TLS handshake per call" —
+    # that handshake was most of the ~0.65s/tile this used to cost.
     def self.fetch_terrarium_tile(z, x, y)
-      response = Net::HTTP.get_response(URI(format(TERRARIUM_URL_TEMPLATE, z: z, x: x, y: y)))
+      uri = URI(format(TERRARIUM_URL_TEMPLATE, z: z, x: x, y: y))
+      http = (Thread.current[:maptool_terrarium_http] ||= Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https"))
+      response = http.get(uri.request_uri)
       response.is_a?(Net::HTTPSuccess) ? response.body : nil
     rescue StandardError
       nil