Add :static_headers setting for custom headers in static file responses (#2089)

otthe · dentarg · web-flow · commit 91cfb548c9e5 · 2025-04-25T16:40:40.000+02:00
This PR implements recent feature request related to static file
responses. It introduces a new configuration setting, `:static_headers`,
which allows developers to define custom headers that will be applied to
all static file responses served by `static!` -method.

Sinatra serves static files directly via `static!`, bypassing filters
and middleware. This makes it so that there is no good ways to add
headers like `Access-Control-Allow-Origin`, which are often needed for
CORS access (e.g., when using fonts or images on canvas).

Co-authored-by: Patrik Ragnarsson &lt;patrik@starkast.net&gt;
diff --git a/README.md b/README.md
@@ -420,6 +420,15 @@ Note that the public directory name is not included in the URL. A file
 Use the `:static_cache_control` setting (see [below](#cache-control)) to add
 `Cache-Control` header info.
 
+By default, Sinatra serves static files from the `public/` folder without running middleware or filters. To add custom headers (e.g, for CORS or caching), use the `:static_headers` setting:
+
+```ruby
+  set :static_headers, {
+    'access-control-allow-origin' => '*',
+    'x-static-asset' => 'served-by-sinatra'
+  }
+```
+
 ## Views / Templates
 
 Each template language is exposed via its own rendering method. These
@@ -2157,6 +2166,16 @@ set :protection, :session => true
       <tt>set :static_cache_control, [:public, :max_age => 300]</tt>
     </dd>
 
+  <dt>static_headers</dt>
+    <dd>
+      Allows you to define custom header settings for static file responses.
+    </dd>
+    <dd>
+      For example: <br>
+      <tt>set :static_headers, {'access-control-allow-origin' => '*', 'x-static-asset' => 'served-by-sinatra'}</tt>
+    </dd>
+
+
   <dt>threaded</dt>
     <dd>
       If set to <tt>true</tt>, will tell server to use
diff --git a/lib/sinatra/base.rb b/lib/sinatra/base.rb
@@ -1143,6 +1143,7 @@ def route_missing
 
     # Attempt to serve static files from public directory. Throws :halt when
     # a matching file is found, returns nil otherwise.
+    # If custom static headers are defined, use them.
     def static!(options = {})
       return if (public_dir = settings.public_folder).nil?
 
@@ -1156,6 +1157,9 @@ def static!(options = {})
 
       env['sinatra.static_file'] = path
       cache_control(*settings.static_cache_control) if settings.static_cache_control?
+
+      headers(settings.static_headers) if settings.static_headers?
+
       send_file path, options.merge(disposition: nil)
     end
 
@@ -2011,6 +2015,8 @@ class << self
     set :public_folder, proc { root && File.join(root, 'public') }
     set :static, proc { public_folder && File.exist?(public_folder) }
     set :static_cache_control, false
+    
+    set :static_headers, {}
 
     error ::Exception do
       response.status = 500
diff --git a/test/static_test.rb b/test/static_test.rb
@@ -273,4 +273,35 @@ def assert_valid_range(http_range, range, path, file)
     assert response.headers.include?('Last-Modified')
   end
 
+  it 'applies custom headers defined in static_headers setting' do
+    mock_app do
+      set :static, true
+      set :public_folder, __dir__
+      set :static_headers, {
+        'access-control-allow-origin' => '*',
+        'x-static-test' => 'yes'
+      }
+    end
+
+    get "/#{File.basename(__FILE__)}"
+    assert ok?
+    assert_equal '*', response['access-control-allow-origin']
+    assert_equal 'yes', response['x-static-test']
+  end
+
+  it 'respects both static_cache_control and static_headers settings together' do
+    mock_app do
+      set :static, true
+      set :public_folder, __dir__
+      set :static_cache_control, [:public, max_age: 3600]
+      set :static_headers, { 'x-static-test' => 'yes' }
+    end
+
+    get "/#{File.basename(__FILE__)}"
+    assert ok?
+    assert_equal 'yes', response['x-static-test']
+    assert_includes response['cache-control'], 'public'
+    assert_match(/max-age=3600/, response['cache-control'])
+  end
+
 end
