placeholder-image 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1b9fc489b1812d0f1f82cbc9bfa765d6e01cdba612da2697a416bbcbc460ae0e
-  data.tar.gz: 1e0d6fe2e8fd81ca37bad24219771fd4125190e92d1f0a9cdc0b216b526ef7d5
+  metadata.gz: 2e4bba850d4f417d66bad57f0453411c81c21b01e6a87fdcd66fffe8b87b5d00
+  data.tar.gz: b3c4d216ab6ac08e03c0058df1caa3024d3a491134f3b6bb332efb65bfce9d85
 SHA512:
-  metadata.gz: 28682fa1cfa37908f42663ba841ff50de20dcb578d7cbeabd8eb09b46e32bd67b92d1d2cabcb8010d1a1cba1469f3de68b43b690b0858fbcb5f65797a749d236
-  data.tar.gz: ddd2662d54dbdf2bd81125763a3ccf9cf4c927e57e32a2952cab2e47f76f446f13ffa3c959b9ceab41d04a19443a552f1c6a8a4e38868fc9ec8c4e9d1337a877
+  metadata.gz: 73e14b26d74235e274609bf768db885de909c1d00cdeaa1515c941568f726877bf1e92731a2712f9b29054a783ee74643b76f3a15febe10280194ca53dcd0225
+  data.tar.gz: cd28a77f3fa31481dbfd111fee819c140562ec26e0b882523e34232e974ffef3be3c9c34aa9460f8d9c0ff89a2de8f439c519ebf4e49303a16e8f97f366dbe56

data/CHANGELOG.md

@@ -3,6 +3,15 @@
 All notable changes to this project will be documented here. This project follows
 [Semantic Versioning](https://semver.org/).
 
+## v1.1.0 - 2026-08-05
+
+  - Validate configuration at boot: unknown option keys and invalid default colors now raise `ArgumentError` when the middleware is constructed. 
+  - Narrow path ownership to `<path_prefix>/`: the bare prefix (`/placeholder`) and sibling paths such as `/placeholder.css` are now passed through to the downstream application instead of returning `400 Bad Request`.
+  - Include the `Allow` header in `405 Method Not Allowed` responses.
+  - Truncate client-supplied color values echoed in `400 Bad Request` messages.
+  - Make container builds reproducible: `docker/Gemfile.lock` is now committed and the image build installs with a frozen bundle.
+  - Publish multi-architecture container images to GitHub Container Registry (`ghcr.io/rodw/placeholder-image`) on release.
+
 ## v1.0.0 - 2026-08-05
 
   - Initial release. Includes PNG-generating Rack middleware, stand-alone Docker service, and complete examples of integrating with Sinatra, Rails, and generic Rack applications.

data/README.md

@@ -90,6 +90,7 @@ use PlaceholderImage::Middleware,
 | `image_default_fg` | `[0x99,0x99,0x99]`| Default foreground color used for the border and dimension label. It accepts the same array and hex-string formats as `image_default_bg`; the request's `fg` parameter overrides it. |
 | `cache_max_entries` | `128` | Maximum number of generated images retained in each middleware instance's in-memory FIFO cache. Set to `0` to disable caching. |
 
+Note that cached entries are compressed PNGs, so worst-case cache memory is roughly `cache_max_entries` times the compressed size of the largest allowed image. Under the default configuration (128 entries, max size 4000x4000 pixels) the largest image encodes to roughly 260 KB yielding a max cache size around 35 MB.
 
 ## Running as a Stand-Alone Container
 

data/lib/placeholder_image/middleware.rb

@@ -12,6 +12,10 @@ require "digest"
 #   GET /placeholder/640x480.png         -> 640x480, default colors
 #   GET /placeholder/300x200.png?bg=eee&fg=999 -> 300x200, specified colors
 #
+# Only requests beginning with "<path_prefix>/" are handled; everything else
+# (including the bare prefix and sibling paths such as "/placeholder.css") is
+# passed through to the downstream application.
+#
 # No image gems required: PNGs are encoded with stdlib zlib.
 module PlaceholderImage
   class BadRequest < StandardError; end
@@ -30,6 +34,9 @@ module PlaceholderImage
 
     DIMENSION = /[1-9]\d*/
 
+    # Maximum length of a client-supplied value echoed back in an error message.
+    ERROR_VALUE_MAX_LENGTH = 32
+
     # @param app [#call] the downstream Rack application.
     # @param options [Hash] configuration overrides merged over {DEFAULTS}.
     # @option options [String] :path_prefix ("/placeholder") URL prefix the middleware serves.
@@ -39,14 +46,19 @@ module PlaceholderImage
     # @option options [Integer] :cache_max_entries (128) in-memory FIFO cache size; +0+ disables caching.
     # @option options [Array(Integer, Integer, Integer), String] :image_default_bg default background color.
     # @option options [Array(Integer, Integer, Integer), String] :image_default_fg default foreground color.
+    # @raise [ArgumentError] if an option key is not present in {DEFAULTS} or a default color is invalid.
     def initialize(app, **options)
+      unknown = options.keys - DEFAULTS.keys
+      raise ArgumentError, "unknown option(s): #{unknown.join(', ')}" unless unknown.empty?
+
       @app     = app
       @options = DEFAULTS.merge(options)
+      %i[image_default_bg image_default_fg].each { |key| @options[key] = resolve_default_color(key) }
       @cache   = {}
       @mutex   = Mutex.new
 
       path_prefix = Regexp.escape(@options[:path_prefix].chomp("/"))
-      @owned = %r{\A#{path_prefix}(?:[./]|\z)}
+      @owned = %r{\A#{path_prefix}/}
       @route = %r{\A#{path_prefix}/(#{DIMENSION})(?:x(#{DIMENSION}))?\.png\z}
     end
 
@@ -56,7 +68,9 @@ module PlaceholderImage
     # @return [Array(Integer, Hash, Array)] a Rack response tuple.
     def call(env)
       return @app.call(env) unless @owned.match?(env["PATH_INFO"])
-      return error(env["REQUEST_METHOD"], 405, "method not allowed") unless %w[GET HEAD].include?(env["REQUEST_METHOD"])
+      unless %w[GET HEAD].include?(env["REQUEST_METHOD"])
+        return error(env["REQUEST_METHOD"], 405, "method not allowed", { "allow" => "GET, HEAD" })
+      end
 
       spec = parse(env["PATH_INFO"], env["QUERY_STRING"].to_s)
       etag = etag_for(spec)
@@ -88,25 +102,37 @@ module PlaceholderImage
       %("#{Digest::SHA256.hexdigest(spec.inspect)[0, 16]}")
     end
 
-    def error(req_method, status, message)
+    def error(req_method, status, message, headers = {})
       body = req_method == "HEAD" ? "" : "#{message}\n"
 
       [
         status,
-        { "content-type" => "text/plain; charset=utf-8",
-          "content-length" => body.bytesize.to_s },
+        headers.merge(
+          "content-type" => "text/plain; charset=utf-8",
+          "content-length" => body.bytesize.to_s
+        ),
         [body]
       ]
     end
 
+    # Fetch the image from the cache if available; otherwise generate (and cache).
+    #
+    # NOTE: Cached entries are compressed PNGs, so worst-case cache memory is
+    #       ~ cache_max_entries * compressed_size_of_largest_allowed_image.
+    #       Under the default config (entries=128 max_px=4000x4000) the largest
+    #       image encodes to ~260 KB; yielding max ~35 MB per cache instance.
     def fetch(spec)
       @mutex.synchronize { return @cache[spec] if @cache.key?(spec) }
 
+      # render outside the mutex: concurrent misses may trigger duplicate rendering
+      # but that's better (cheap, idempotent) than serializing all rendering
       img = Renderer.call(**spec)
 
-      @mutex.synchronize do
-        @cache[spec] = img if @options[:cache_max_entries].positive?
-        @cache.shift while @cache.size > @options[:cache_max_entries] # FIFO eviction
+      if @options[:cache_max_entries].positive?
+        @mutex.synchronize do
+          @cache[spec] = img
+          @cache.shift while @cache.size > @options[:cache_max_entries] # FIFO eviction
+        end
       end
 
       img
@@ -148,14 +174,35 @@ module PlaceholderImage
     end
 
     def parse_color(value, default)
-      value = default if value.nil? || value.empty?
-      return value if value.is_a?(Array)
+      return default if value.nil? || value.empty?
+
+      parse_hex_color(value) or raise BadRequest, "invalid color: #{truncate(value)}"
+    end
 
+    # @return [Array(Integer, Integer, Integer), nil] RGB bytes, or +nil+ if malformed.
+    def parse_hex_color(value)
       hex = value.delete_prefix("#")
       hex = hex.chars.map { |c| c * 2 }.join if hex.length == 3
-      raise BadRequest, "invalid color: #{value}" unless hex.match?(/\A\h{6}\z/)
+      return nil unless hex.match?(/\A\h{6}\z/)
 
       [hex[0, 2], hex[2, 2], hex[4, 2]].map { |pair| pair.to_i(16) }
     end
+
+    def truncate(value)
+      value.length > ERROR_VALUE_MAX_LENGTH ? "#{value[0, ERROR_VALUE_MAX_LENGTH]}..." : value
+    end
+
+    # Validates and resolves a configured default color to RGB bytes at boot.
+    def resolve_default_color(key)
+      value = @options[key]
+      if value.is_a?(Array)
+        return value if value.length == 3 && value.all? { |c| c.is_a?(Integer) && c.between?(0, 255) }
+      elsif value.is_a?(String)
+        rgb = parse_hex_color(value)
+        return rgb if rgb
+      end
+
+      raise ArgumentError, "invalid #{key}: expected hex color string or array of RGB integers, got #{value.inspect}"
+    end
   end
 end

data/lib/placeholder_image/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PlaceholderImage
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end

data/sig/placeholder_image/middleware.rbs

@@ -9,6 +9,7 @@ module PlaceholderImage
 
     DEFAULTS: Hash[Symbol, untyped]
     DIMENSION: Regexp
+    ERROR_VALUE_MAX_LENGTH: Integer
 
     @app: untyped
     @options: Hash[Symbol, untyped]
@@ -29,7 +30,7 @@ module PlaceholderImage
 
     def etag_for: (untyped spec) -> String
 
-    def error: (untyped req_method, Integer status, String message) -> rack_response
+    def error: (untyped req_method, Integer status, String message, ?Hash[String, String] headers) -> rack_response
 
     def fetch: (untyped spec) -> String
 
@@ -40,5 +41,11 @@ module PlaceholderImage
     def parse_query_string: (untyped query) -> Hash[String, String]
 
     def parse_color: (untyped value, untyped default) -> Array[Integer]
+
+    def parse_hex_color: (String value) -> Array[Integer]?
+
+    def truncate: (String value) -> String
+
+    def resolve_default_color: (Symbol key) -> Array[Integer]
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: placeholder-image
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Rodney Waldhoff