rack-server-pages 0.2.0 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/CHANGES.md +22 -0
- data/README.md +222 -78
- data/RELEASING.md +79 -0
- data/UPGRADING.md +23 -0
- data/lib/rack/server_pages.rb +84 -7
- data/lib/rack-server-pages/version.rb +1 -1
- data/rack-server-pages.gemspec +3 -6
- metadata +8 -63
- data/.github/workflows/lint.yml +0 -15
- data/.github/workflows/test.yml +0 -37
- data/.gitignore +0 -11
- data/.rspec +0 -2
- data/.rubocop.yml +0 -10
- data/.rubocop_todo.yml +0 -372
- data/Gemfile +0 -46
- data/Guardfile +0 -16
- data/Rakefile +0 -12
- data/config.ru +0 -49
- data/public/CHANGES.erb +0 -3
- data/public/README.erb +0 -3
- data/public/_layout.html.erb +0 -9
- data/public/folder/sample.erb +0 -14
- data/public/folder/special-sub.folder-@/sample.erb +0 -14
- data/public/folder/subfolder/(sub-folder)/sample-in-sub-folder.extension.erb +0 -14
- data/public/folder/subfolder/sample.erb +0 -14
- data/public/folder//320/277/320/276-/321/200/321/203/321/201/321/201/320/272/320/270//320/277/321/200/320/270/320/274/320/265/321/200.erb +0 -14
- data/public/index.html +0 -23
- data/public/info.php +0 -89
- data/public/rack_logo.png +0 -0
- data/public/rack_logo@2x.png +0 -0
- data/public/sample.erb +0 -14
- data/public/style.css.sass +0 -99
- data/views/about.html.slim +0 -11
- data/views/article.html.md +0 -16
- data/views/betty.css.sass +0 -11
- data/views/contact.xml.builder +0 -5
- data/views/examples/_layout.html.erb +0 -14
- data/views/examples/_time.html.erb +0 -4
- data/views/examples/builder.xml.builder +0 -2
- data/views/examples/coffee.js.coffee +0 -0
- data/views/examples/erb.html.erb +0 -2
- data/views/examples/haml.html.haml +0 -6
- data/views/examples/html.html +0 -1
- data/views/examples/index.html.erb +0 -9
- data/views/examples/less.css.less +0 -0
- data/views/examples/liquid.html.liquid +0 -0
- data/views/examples/markaby.html.mab +0 -0
- data/views/examples/markdown.html.markdown +0 -6
- data/views/examples/nokogiri.xml.nokogiri +0 -1
- data/views/examples/radius.html.radius +0 -0
- data/views/examples/rdoc.html.rdoc +0 -0
- data/views/examples/robots.txt +0 -1
- data/views/examples/sass.css.sass +0 -11
- data/views/examples/scss.css.scss +0 -0
- data/views/examples/slim.html.slim +0 -2
- data/views/examples/source.html.slim +0 -9
- data/views/examples/textile.html.textile +0 -0
- data/views/examples/wiki.html.wiki +0 -0
- data/views/examples/yajl.json.yajl +0 -0
- data/views/script.js.coffee +0 -13
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: e901e5e22aabc19775de43f94a34d3ae8a8b27a4469db4563f9e78052350cc38
|
|
4
|
+
data.tar.gz: b853d1e26f38fd0ecb79c53f51415d5e907a30ce5c7ab5b9e92e2697f1539897
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: c6f387713227b1a9d7495d8763b6817305882999484fb0318d25fccd610781ff70222138d740a86f9cc3d716a55b336db3b33285e6ef9fdf24f27c88c56d91e8
|
|
7
|
+
data.tar.gz: 8fac86b85b2a9bb9aef795faf61036c2479ffe83171c4a3d2e63f6f096d19eb882f8f5128c51abccb1a08011fc3e31a6dfd087cd1a31dfadd6aaf74f7feaf4c7
|
data/CHANGES.md
CHANGED
|
@@ -1,6 +1,28 @@
|
|
|
1
1
|
CHANGES
|
|
2
2
|
=======
|
|
3
3
|
|
|
4
|
+
### [v0.3.0](https://github.com/migrs/rack-server-pages/releases/tag/v0.3.0) / 2026-10-25
|
|
5
|
+
|
|
6
|
+
* [Changes](https://github.com/migrs/rack-server-pages/compare/v0.2.1...v0.3.0)
|
|
7
|
+
|
|
8
|
+
* Feature
|
|
9
|
+
- Add content-versioned asset URLs, `static_etags` and `static_timestamps` (both enabled by default), and configurable static cache headers. See [UPGRADING](UPGRADING.md) for caching changes.
|
|
10
|
+
|
|
11
|
+
* Bugfix
|
|
12
|
+
- Detect the loaded Tilt template API rather than an incomplete namespace created by another dependency.
|
|
13
|
+
|
|
14
|
+
* Misc
|
|
15
|
+
- Enable line and branch coverage with SimpleCov and publish coverage to Coveralls from CI.
|
|
16
|
+
- Refresh the README, move its backlog into GitHub issues, and document rendering a template with `halt`.
|
|
17
|
+
- Modernize GitHub Actions and test Ruby 3.0 through 3.4 and 4.0 against Rack 2.2 and 3 with headless Firefox.
|
|
18
|
+
|
|
19
|
+
### [v0.2.1](https://github.com/migrs/rack-server-pages/releases/tag/v0.2.1) / 2025-08-31
|
|
20
|
+
|
|
21
|
+
* [Changes](https://github.com/migrs/rack-server-pages/compare/v0.2.0...v0.2.1)
|
|
22
|
+
|
|
23
|
+
* Bugfix
|
|
24
|
+
- Stop using `Rack::Logger`
|
|
25
|
+
|
|
4
26
|
### [v0.2.0](https://github.com/migrs/rack-server-pages/releases/tag/v0.2.0) / 2024-10-19
|
|
5
27
|
|
|
6
28
|
* [Changes](https://github.com/migrs/rack-server-pages/compare/v0.1.0...v0.2.0)
|
data/README.md
CHANGED
|
@@ -1,18 +1,20 @@
|
|
|
1
1
|
Rack Server Pages
|
|
2
2
|
=================
|
|
3
3
|
|
|
4
|
-
Rack middleware and application for serving dynamic pages in
|
|
5
|
-
There are no controllers or models, just only views like a jsp, asp and php!
|
|
4
|
+
Rack middleware and application for serving dynamic pages without controllers or models, using templates similar to JSP, ASP, and PHP. Requests map directly to files in your view directories. Built-in ERB works without extra runtime dependencies beyond Rack; Tilt and additional template engines are optional.
|
|
6
5
|
|
|
7
|
-
<
|
|
6
|
+
<https://github.com/migrs/rack-server-pages>
|
|
8
7
|
|
|
9
8
|
[](https://github.com/migrs/rack-server-pages/actions/workflows/test.yml)
|
|
10
|
-
[](https://coveralls.io/github/migrs/rack-server-pages?branch=master)
|
|
10
|
+
[](https://badge.fury.io/rb/rack-server-pages)
|
|
11
11
|
|
|
12
12
|
## Features
|
|
13
13
|
|
|
14
14
|
- Serving dynamic pages (default: ERB)
|
|
15
15
|
- Serving static files
|
|
16
|
+
- Content-versioned asset URLs with `asset_path`
|
|
17
|
+
- Configurable static-file caching with content-based `ETag` headers and timestamp validation
|
|
16
18
|
- No requirements (except Rack)
|
|
17
19
|
- Tilt support (optional)
|
|
18
20
|
- Include a partial template
|
|
@@ -25,12 +27,16 @@ There are no controllers or models, just only views like a jsp, asp and php!
|
|
|
25
27
|
|
|
26
28
|
## Requirements
|
|
27
29
|
|
|
28
|
-
- [Ruby](
|
|
29
|
-
- [Rack](
|
|
30
|
+
- [Ruby](https://www.ruby-lang.org/)
|
|
31
|
+
- [Rack](https://github.com/rack/rack)
|
|
32
|
+
|
|
33
|
+
CI tests Ruby 3.0 through 3.4 and 4.0 against Rack 2.2 and 3, including browser integration tests with headless Firefox. Selenium manages the browser driver automatically.
|
|
34
|
+
|
|
35
|
+
The test suite collects line and branch coverage with SimpleCov before loading the library, including unexecuted files under `lib/`. Run `bundle exec rake spec` and open `coverage/index.html` to inspect the local report. CI publishes `coverage/.resultset.json` to Coveralls from the Ruby 4.0 / Rack 3 job only, so compatibility jobs do not overwrite each other's reports. Coverage output is ignored by Git.
|
|
30
36
|
|
|
31
37
|
## Install
|
|
32
38
|
|
|
33
|
-
[RubyGems](
|
|
39
|
+
Available on [RubyGems](https://rubygems.org/gems/rack-server-pages):
|
|
34
40
|
|
|
35
41
|
```
|
|
36
42
|
gem install rack-server-pages
|
|
@@ -83,30 +89,30 @@ And same as above.
|
|
|
83
89
|
|
|
84
90
|
## Template bindings
|
|
85
91
|
|
|
86
|
-
- CoreHelper
|
|
87
|
-
- layout(file)
|
|
88
|
-
- partial(file)
|
|
89
|
-
- redirect(target, status=302) (same as [Sinatra](http://www.sinatrarb.com/intro#Browser%20Redirect))
|
|
90
|
-
- halt(
|
|
91
|
-
- url(path)
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
-
|
|
96
|
-
-
|
|
97
|
-
-
|
|
98
|
-
-
|
|
99
|
-
-
|
|
100
|
-
|
|
101
|
-
- [Rack::Response](
|
|
102
|
-
- response
|
|
103
|
-
- headers
|
|
104
|
-
-
|
|
105
|
-
-
|
|
106
|
-
|
|
107
|
-
- [ERB::Util](
|
|
108
|
-
- h (alias for:
|
|
109
|
-
- u (alias for:
|
|
92
|
+
- `CoreHelper`
|
|
93
|
+
- `layout(file)`
|
|
94
|
+
- `partial(file)`
|
|
95
|
+
- `redirect(target, status=302)` (same as [Sinatra](http://www.sinatrarb.com/intro#Browser%20Redirect))
|
|
96
|
+
- `halt(*args)` (same as [Sinatra](http://www.sinatrarb.com/intro#Halting))
|
|
97
|
+
- `url(path)`
|
|
98
|
+
- `asset_path(path)`
|
|
99
|
+
|
|
100
|
+
- [`Rack::Request`](https://www.rubydoc.info/gems/rack/Rack/Request)
|
|
101
|
+
- `request`
|
|
102
|
+
- `env`
|
|
103
|
+
- `params`
|
|
104
|
+
- `session`
|
|
105
|
+
- `cookies`
|
|
106
|
+
|
|
107
|
+
- [`Rack::Response`](https://www.rubydoc.info/gems/rack/Rack/Response)
|
|
108
|
+
- `response`
|
|
109
|
+
- `headers`
|
|
110
|
+
- `set_cookies`
|
|
111
|
+
- `delete_cookie`
|
|
112
|
+
|
|
113
|
+
- [`ERB::Util`](https://docs.ruby-lang.org/en/master/ERB/Util.html)
|
|
114
|
+
- `h` (alias for: `html_escape`)
|
|
115
|
+
- `u` (alias for: `url_encode`)
|
|
110
116
|
|
|
111
117
|
## Configurations
|
|
112
118
|
|
|
@@ -144,21 +150,148 @@ run Rack::ServerPages.new { |config|
|
|
|
144
150
|
|
|
145
151
|
### Options
|
|
146
152
|
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
153
|
+
#### `view_path`
|
|
154
|
+
|
|
155
|
+
Sets the directories searched for templates and static files, in priority order. Accepts one directory or an array; the first matching file is used.
|
|
156
|
+
|
|
157
|
+
Default: `['views', 'public']`.
|
|
158
|
+
|
|
159
|
+
```ruby
|
|
160
|
+
config.view_path = ['site/views', 'site/public']
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
#### `effective_path`
|
|
164
|
+
|
|
165
|
+
Limits file serving to a URL prefix and removes that prefix when resolving files. Requests outside the prefix fall through to the downstream or fallback application.
|
|
166
|
+
|
|
167
|
+
Default: `nil` (no prefix).
|
|
168
|
+
|
|
169
|
+
```ruby
|
|
170
|
+
config.effective_path = '/pages'
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
This serves `/pages/about.html` from `about.html` under a configured `view_path` directory.
|
|
174
|
+
|
|
175
|
+
#### `default_charset`
|
|
176
|
+
|
|
177
|
+
Sets the default charset in rendered template responses' `Content-Type` header. Does not convert file contents or change static-file headers.
|
|
178
|
+
|
|
179
|
+
Default: `'utf-8'`.
|
|
180
|
+
|
|
181
|
+
```ruby
|
|
182
|
+
config.default_charset = 'utf-8'
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
#### `cache_control`
|
|
186
|
+
|
|
187
|
+
Sets the default `Cache-Control` response header for rendered templates, including generated CSS. A header explicitly set by a template or filter takes precedence. Static files use `static_cache_control` instead.
|
|
188
|
+
|
|
189
|
+
Default: `nil` (no policy added).
|
|
190
|
+
|
|
191
|
+
```ruby
|
|
192
|
+
config.cache_control = 'private, no-store'
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
This prevents caching pages containing sensitive information.
|
|
196
|
+
|
|
197
|
+
#### `static_cache_control`
|
|
198
|
+
|
|
199
|
+
Sets the `Cache-Control` response header for static files such as CSS, JavaScript, and images. Rendered templates, including generated CSS, use `cache_control` instead.
|
|
200
|
+
|
|
201
|
+
Default: `nil` (no policy added).
|
|
202
|
+
|
|
203
|
+
```ruby
|
|
204
|
+
config.static_cache_control = 'public, no-cache'
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
This allows caching but requires revalidation before reuse.
|
|
208
|
+
|
|
209
|
+
#### `static_etags`
|
|
210
|
+
|
|
211
|
+
Adds a content-based `ETag` response header to static files by hashing each file with SHA-256 on each request. A matching `If-None-Match` returns an empty `304` for `GET`/`HEAD` and takes precedence over `If-Modified-Since`.
|
|
212
|
+
|
|
213
|
+
Default: `true`.
|
|
214
|
+
|
|
215
|
+
```ruby
|
|
216
|
+
config.static_etags = false
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
This disables content hashing, `ETag` generation, and `ETag` validation without disabling `static_timestamps` or `asset_path`.
|
|
220
|
+
|
|
221
|
+
#### `static_timestamps`
|
|
222
|
+
|
|
223
|
+
Honors `If-Modified-Since` on static requests using Rack's timestamp-based conditional handling, unless enabled `static_etags` validation takes precedence.
|
|
224
|
+
|
|
225
|
+
Default: `true`.
|
|
226
|
+
|
|
227
|
+
```ruby
|
|
228
|
+
config.static_timestamps = false
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
This ignores `If-Modified-Since` when deployment timestamps are unreliable. The `Last-Modified` response header and `static_etags` validation are unaffected.
|
|
232
|
+
|
|
233
|
+
#### `failure_app`
|
|
234
|
+
|
|
235
|
+
Sets a fallback Rack application for requests that do not resolve to a template or static file. When used as middleware, the downstream application takes precedence over this setting.
|
|
236
|
+
|
|
237
|
+
Default: `nil` (uses the built-in `404` response when no downstream application is supplied).
|
|
150
238
|
|
|
151
|
-
|
|
152
|
-
|
|
239
|
+
```ruby
|
|
240
|
+
config.failure_app = ->(_env) { [404, { 'content-type' => 'text/plain' }, ['Page not found']] }
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
#### `show_exceptions`
|
|
244
|
+
|
|
245
|
+
Controls whether template-rendering errors are raised to the caller or handled as a `500` response with `on_error` filters. Does not control a built-in error page.
|
|
246
|
+
|
|
247
|
+
Default: `nil` (raises when `RACK_ENV` is unset or `'development'`; handles errors in other environments).
|
|
248
|
+
|
|
249
|
+
```ruby
|
|
250
|
+
config.show_exceptions = false
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
This handles template errors instead of raising them.
|
|
254
|
+
|
|
255
|
+
### Versioned assets and browser caching
|
|
256
|
+
|
|
257
|
+
Content-based `ETag` validation and versioned asset URLs work independently. With `static_etags = true` (the default), ordinary URLs such as `/styles.css` receive `ETag` headers and support `If-None-Match` without using `asset_path`. However, validators only help when the browser makes a request; they cannot prevent reuse of an asset that the browser considers fresh. `asset_path` changes the URL when the file contents change, so a browser fetching fresh HTML requests the new asset URL instead of reusing the old one. Use both for stronger stale-asset protection.
|
|
258
|
+
|
|
259
|
+
Use `asset_path` instead of a fixed local asset URL in templates:
|
|
260
|
+
|
|
261
|
+
```erb
|
|
262
|
+
<link rel="stylesheet" href="<%= h asset_path('/styles.css') %>">
|
|
263
|
+
<script src="<%= h asset_path('/scripts/app.js') %>"></script>
|
|
264
|
+
<img src="<%= h asset_path('/img/logo.png') %>" alt="Logo">
|
|
265
|
+
```
|
|
153
266
|
|
|
154
|
-
-
|
|
155
|
-
- default: utf-8
|
|
267
|
+
The helper adds a SHA-256 content fingerprint, for example `/styles.css?v=...`. Changed file contents produce a new URL even when a deployment preserves file timestamps and sizes. Existing query parameters and fragments are preserved, and an existing `v` parameter is replaced. Paths are relative to the configured view paths; application mounts (`SCRIPT_NAME`) and `effective_path` are included automatically. Missing files raise `Errno::ENOENT`; external URLs and parent-directory traversal are rejected.
|
|
156
268
|
|
|
157
|
-
|
|
158
|
-
|
|
269
|
+
Configure browser revalidation explicitly:
|
|
270
|
+
|
|
271
|
+
```ruby
|
|
272
|
+
use Rack::ServerPages do |config|
|
|
273
|
+
config.cache_control = 'private, no-cache'
|
|
274
|
+
config.static_cache_control = 'public, no-cache'
|
|
275
|
+
end
|
|
276
|
+
```
|
|
159
277
|
|
|
160
|
-
-
|
|
161
|
-
|
|
278
|
+
Both settings default to `nil`, preserving the existing cache-policy defaults. `no-cache` permits storage but requires revalidation before reuse; use `private, no-store` instead for templates containing sensitive account or payment information. These settings do not change cache headers on the downstream application.
|
|
279
|
+
|
|
280
|
+
By default, static responses include content-based `ETag` headers, hashing the file on each request. Matching `If-None-Match` requests return an empty `304` response. When both validators are present, `If-None-Match` takes precedence over `If-Modified-Since`, so a changed file is returned for an old `ETag` even if its modification time is unchanged. Requests with only `If-Modified-Since` retain Rack's timestamp-based conditional handling.
|
|
281
|
+
|
|
282
|
+
Set `config.static_etags = false` to disable content hashing and content-based `ETag` validation. With the default timestamp-validation setting, this restores Rack's original static-file conditional handling. `static_cache_control` still applies, and `asset_path` remains available independently. See [UPGRADING](UPGRADING.md) when updating from an earlier release.
|
|
283
|
+
|
|
284
|
+
`static_timestamps` also defaults to `true`. Set `config.static_timestamps = false` to ignore timestamp-based request validation when deployment timestamps are unreliable. This does not remove the `Last-Modified` response header or disable `ETag` validation. Set both options to `false` to disable both conditional checks.
|
|
285
|
+
|
|
286
|
+
Use the helper for local images, fonts, icons, and other assets too. For URLs inside CSS, rename the stylesheet to `styles.css.erb` and render those references explicitly:
|
|
287
|
+
|
|
288
|
+
```erb
|
|
289
|
+
.hero { background-image: url("<%= asset_path('/img/background.svg') %>"); }
|
|
290
|
+
```
|
|
291
|
+
|
|
292
|
+
Continue linking to `/styles.css` through `asset_path`. The fingerprint identifies the selected source file; generated CSS must also use `cache_control = 'private, no-cache'` so changes to a referenced image are picked up even when the CSS template itself has not changed. Referenced files are not rewritten automatically, and no build pipeline is needed.
|
|
293
|
+
|
|
294
|
+
Do not set `immutable` or a long freshness lifetime for these query-versioned URLs: the middleware serves the current file, not an archive of old versions. This mechanism does not force an already-open page to reload; the new URLs take effect when it fetches fresh HTML.
|
|
162
295
|
|
|
163
296
|
### Helpers
|
|
164
297
|
|
|
@@ -174,7 +307,7 @@ use Rack::ServerPages do |config|
|
|
|
174
307
|
end
|
|
175
308
|
```
|
|
176
309
|
|
|
177
|
-
in view file (erb)
|
|
310
|
+
in view file (`.erb`)
|
|
178
311
|
|
|
179
312
|
```erb
|
|
180
313
|
<%= three_times('blah') %>
|
|
@@ -212,7 +345,7 @@ end
|
|
|
212
345
|
|
|
213
346
|
### Filters
|
|
214
347
|
|
|
215
|
-
with before
|
|
348
|
+
with `before`/`after` block
|
|
216
349
|
|
|
217
350
|
```ruby
|
|
218
351
|
use Rack::ServerPages do |config|
|
|
@@ -221,7 +354,7 @@ use Rack::ServerPages do |config|
|
|
|
221
354
|
end
|
|
222
355
|
|
|
223
356
|
config.after do
|
|
224
|
-
|
|
357
|
+
Logger.new($stdout).debug('xxxx')
|
|
225
358
|
end
|
|
226
359
|
end
|
|
227
360
|
```
|
|
@@ -231,7 +364,7 @@ with procs
|
|
|
231
364
|
```ruby
|
|
232
365
|
proc1 = proc { @name = 'Jonny' }
|
|
233
366
|
proc2 = proc { @age = 24 }
|
|
234
|
-
proc3 = proc {
|
|
367
|
+
proc3 = proc { Logger.new($stdout).debug('xxxx') }
|
|
235
368
|
|
|
236
369
|
use Rack::ServerPages do |config|
|
|
237
370
|
config.before proc1, proc2
|
|
@@ -239,7 +372,7 @@ use Rack::ServerPages do |config|
|
|
|
239
372
|
end
|
|
240
373
|
```
|
|
241
374
|
|
|
242
|
-
if you define before
|
|
375
|
+
if you define a `before`/`after` method in a helper module, it will be treated as a filter
|
|
243
376
|
|
|
244
377
|
```ruby
|
|
245
378
|
module SampleHelper
|
|
@@ -263,9 +396,26 @@ in view file
|
|
|
263
396
|
<%= three_times(@title) %>
|
|
264
397
|
```
|
|
265
398
|
|
|
399
|
+
### Rendering a template with `halt`
|
|
400
|
+
|
|
401
|
+
`partial` returns a rendered string, so pass its result to `halt` as the response body. For example, create `views/forbidden.html.erb`:
|
|
402
|
+
|
|
403
|
+
```erb
|
|
404
|
+
<h1><%= 'Forbidden' %></h1>
|
|
405
|
+
```
|
|
406
|
+
|
|
407
|
+
Inside a `before` filter, helper, or template, return that page with the desired status and content type:
|
|
408
|
+
|
|
409
|
+
```ruby
|
|
410
|
+
halt 403, { Rack::CONTENT_TYPE => 'text/html; charset=utf-8' }, partial('views/forbidden.html')
|
|
411
|
+
```
|
|
412
|
+
|
|
413
|
+
Place the call inside your existing validation or authorization check. `partial` takes a filesystem path relative to the working directory, or an absolute path; it does not search `view_path` automatically. Omitting the final `.erb` suffix lets it find the template. `halt` skips normal page rendering, so automatic layouts are not applied to this response. The example works with both built-in ERB and Tilt.
|
|
414
|
+
|
|
266
415
|
## Tilt support
|
|
267
|
-
[Tilt](
|
|
268
|
-
|
|
416
|
+
[Tilt](https://github.com/rtomayko/tilt) is a generic interface to multiple Ruby template engines. To use it, add Tilt and the desired engines to your dependencies, then explicitly require them:
|
|
417
|
+
|
|
418
|
+
Tilt is selected only when its template lookup API is available. A `Tilt` namespace created by another dependency does not enable it or force it to load. Loading Tilt later enables it for subsequent requests unless you have explicitly disabled it with `Rack::ServerPages::Template.use_tilt(false)`.
|
|
269
419
|
|
|
270
420
|
```ruby
|
|
271
421
|
require 'rack-server-pages'
|
|
@@ -274,7 +424,12 @@ require 'rdiscount' # markdown library
|
|
|
274
424
|
run Rack::ServerPages
|
|
275
425
|
```
|
|
276
426
|
|
|
277
|
-
|
|
427
|
+
If your application uses `Bundler.require`, the equivalent `Gemfile` entries are:
|
|
428
|
+
|
|
429
|
+
```ruby
|
|
430
|
+
gem 'tilt', require: 'tilt'
|
|
431
|
+
gem 'rdiscount', require: 'rdiscount'
|
|
432
|
+
```
|
|
278
433
|
|
|
279
434
|
### [Markdown](http://daringfireball.net/projects/markdown/)
|
|
280
435
|
|
|
@@ -469,21 +624,13 @@ At first, create sample file: `public/hello.erb` or `views/hello.html.erb`
|
|
|
469
624
|
|
|
470
625
|
### Rails
|
|
471
626
|
|
|
472
|
-
Add
|
|
627
|
+
Add the middleware inside your application configuration in `config/application.rb`:
|
|
473
628
|
|
|
474
629
|
```ruby
|
|
475
630
|
config.middleware.use Rack::ServerPages
|
|
476
631
|
```
|
|
477
632
|
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
Rails2
|
|
481
|
-
|
|
482
|
-
```
|
|
483
|
-
script/server
|
|
484
|
-
```
|
|
485
|
-
|
|
486
|
-
Rails3
|
|
633
|
+
Start Rails:
|
|
487
634
|
|
|
488
635
|
```
|
|
489
636
|
rails s
|
|
@@ -521,15 +668,15 @@ ruby sinatra_sample.rb
|
|
|
521
668
|
|
|
522
669
|
### Customize file extension associations
|
|
523
670
|
|
|
524
|
-
#### e.g.
|
|
671
|
+
#### e.g. `.php` as ERB
|
|
525
672
|
|
|
526
|
-
ERBTemplate (default)
|
|
673
|
+
`ERBTemplate` (default)
|
|
527
674
|
|
|
528
675
|
```ruby
|
|
529
676
|
Rack::ServerPages::Template::ERBTemplate.extensions << 'php'
|
|
530
677
|
```
|
|
531
678
|
|
|
532
|
-
TiltTemplate (see. [Template Mappings](http://github.com/rtomayko/tilt))
|
|
679
|
+
`TiltTemplate` (see. [Template Mappings](http://github.com/rtomayko/tilt))
|
|
533
680
|
|
|
534
681
|
```ruby
|
|
535
682
|
Tilt.register Tilt::ERBTemplate, 'php'
|
|
@@ -543,25 +690,22 @@ And create `public/info.php` :)
|
|
|
543
690
|
|
|
544
691
|
<http://localhost:9292/info.php>
|
|
545
692
|
|
|
546
|
-
##
|
|
693
|
+
## Development
|
|
694
|
+
|
|
695
|
+
Clone the repository and install its development dependencies. RedCloth and BlueCloth are legacy optional test engines; the C17 build options let them compile when Ruby defaults to C23:
|
|
547
696
|
|
|
548
|
-
|
|
697
|
+
```sh
|
|
698
|
+
bundle config set --local build.RedCloth --with-cflags=-std=gnu17
|
|
699
|
+
bundle config set --local build.bluecloth --with-cflags=-std=gnu17
|
|
700
|
+
bundle install
|
|
701
|
+
MOZ_HEADLESS=1 bundle exec rake
|
|
702
|
+
```
|
|
549
703
|
|
|
550
|
-
|
|
704
|
+
The default task runs lint and the full suite. Browser examples require Firefox; Selenium manages its driver. Run `bundle exec rake spec` for only the tests.
|
|
551
705
|
|
|
552
|
-
|
|
553
|
-
- Static file generator (for designer)
|
|
706
|
+
Run the included application with `bundle exec rackup` and visit <http://localhost:9292/> or <http://localhost:9292/examples/> for local examples. There is no maintained hosted demo.
|
|
554
707
|
|
|
555
|
-
|
|
556
|
-
- Tutorials
|
|
557
|
-
- for PHP user
|
|
558
|
-
- for Designer
|
|
559
|
-
- for Windows user
|
|
560
|
-
- More documents
|
|
561
|
-
- Deployment using apache / passenger / nginx
|
|
562
|
-
- Complete Tilt examples
|
|
563
|
-
- Philosophy
|
|
564
|
-
- Benchmark
|
|
708
|
+
See [RELEASING](RELEASING.md) for the maintainer release process.
|
|
565
709
|
|
|
566
710
|
## License
|
|
567
711
|
|
data/RELEASING.md
ADDED
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
# Releasing Rack Server Pages
|
|
2
|
+
|
|
3
|
+
Release bug fixes frequently, features less frequently, and breaking changes rarely.
|
|
4
|
+
|
|
5
|
+
## Release
|
|
6
|
+
|
|
7
|
+
Start from a clean, up-to-date canonical checkout on `master`. Confirm that `origin` points to `migrs/rack-server-pages`, the version in `lib/rack-server-pages/version.rb` matches the next heading in [CHANGES.md](CHANGES.md), and the version has not already been tagged or published to RubyGems.
|
|
8
|
+
|
|
9
|
+
```sh
|
|
10
|
+
git switch master
|
|
11
|
+
git pull --ff-only origin master
|
|
12
|
+
git status --short
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Run lint and the complete test suite with Firefox available. Selenium manages its driver; use headless mode locally. See [Development](README.md#development) for dependency setup.
|
|
16
|
+
|
|
17
|
+
```sh
|
|
18
|
+
MOZ_HEADLESS=1 bundle exec rake
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Also run the suite against Rack 2.2. The `RACK_VERSION` selector must be set when resolving dependencies and running tests:
|
|
22
|
+
|
|
23
|
+
```sh
|
|
24
|
+
RACK_VERSION='~> 2.2' bundle update rack rackup
|
|
25
|
+
RACK_VERSION='~> 2.2' MOZ_HEADLESS=1 bundle exec rake spec
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
Return to the default Rack 3 dependencies afterward:
|
|
29
|
+
|
|
30
|
+
```sh
|
|
31
|
+
bundle update rack rackup
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
Review [UPGRADING.md](UPGRADING.md) for behavior changes. Replace `Next` in the release heading in `CHANGES.md` with the current date, preserving the existing `YYYY-MM-DD` format. Commit and push the release preparation:
|
|
35
|
+
|
|
36
|
+
```sh
|
|
37
|
+
git add CHANGES.md
|
|
38
|
+
git commit -m "Preparing for release, 0.3.0."
|
|
39
|
+
git push origin master
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Wait for the release commit's [GitHub Actions](https://github.com/migrs/rack-server-pages/actions) checks to pass across the full Ruby/Rack matrix and lint. A successful build for a different commit is not sufficient.
|
|
43
|
+
|
|
44
|
+
Publishing requires a maintainer's RubyGems credentials and may require a fresh one-time password (OTP). For an agent-assisted release, request the OTP immediately before publishing, after validation and CI complete. Never commit or log credentials or OTPs. With `OTP` holding a freshly supplied code:
|
|
45
|
+
|
|
46
|
+
```sh
|
|
47
|
+
GEM_HOST_OTP_CODE="$OTP" bundle exec rake release
|
|
48
|
+
unset OTP
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Bundler builds the gem in `pkg/`, creates the version tag, pushes the commit and tag, and publishes the gem. Verify that the remote tag points to the release commit and RubyGems lists the expected version. If a step fails, inspect what completed before retrying; never move a published release tag or overwrite a published version.
|
|
52
|
+
|
|
53
|
+
Create a GitHub release from the tag, using the corresponding changelog entry as release notes and linking to the upgrade guide for behavior changes:
|
|
54
|
+
|
|
55
|
+
```sh
|
|
56
|
+
gh release create v0.3.0 --verify-tag --title "v0.3.0" --notes-file /path/to/release-notes.md
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
## Prepare the Next Version
|
|
60
|
+
|
|
61
|
+
Increment the patch version in `lib/rack-server-pages/version.rb`, then add a new `Next` section at the top of `CHANGES.md`, updating both its release and comparison links:
|
|
62
|
+
|
|
63
|
+
```markdown
|
|
64
|
+
### [v0.3.1](https://github.com/migrs/rack-server-pages/releases/tag/v0.3.1) / Next
|
|
65
|
+
|
|
66
|
+
* [Changes](https://github.com/migrs/rack-server-pages/compare/v0.3.0...v0.3.1)
|
|
67
|
+
|
|
68
|
+
* Feature
|
|
69
|
+
|
|
70
|
+
* Bugfix
|
|
71
|
+
|
|
72
|
+
* Misc
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
```sh
|
|
76
|
+
git add CHANGES.md lib/rack-server-pages/version.rb
|
|
77
|
+
git commit -m "Preparing for next development iteration, 0.3.1."
|
|
78
|
+
git push origin master
|
|
79
|
+
```
|
data/UPGRADING.md
ADDED
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
# Upgrading
|
|
2
|
+
|
|
3
|
+
## 0.2.x to 0.3.0
|
|
4
|
+
|
|
5
|
+
### Static-file caching changes by default
|
|
6
|
+
|
|
7
|
+
`static_etags` defaults to `true`. Static-file responses now include an ETag derived from a SHA-256 hash of the file contents. Matching `If-None-Match` validators return an empty `304` response for GET and HEAD. When both `If-None-Match` and `If-Modified-Since` are present, the ETag takes precedence: an old ETag produces a full response even if the file's timestamp is unchanged.
|
|
8
|
+
|
|
9
|
+
Requests with only `If-Modified-Since` retain Rack's timestamp-based conditional handling, including `304` responses for matching timestamps. Such requests still rely on accurate modification times; adopt content-versioned asset URLs for protection against deployment tools that preserve or normalize timestamps.
|
|
10
|
+
|
|
11
|
+
The file is read and hashed on each static request, adding disk and CPU work. To restore Rack's original static-file conditional handling without this content hashing, disable the option:
|
|
12
|
+
|
|
13
|
+
```ruby
|
|
14
|
+
use Rack::ServerPages do |config|
|
|
15
|
+
config.static_etags = false
|
|
16
|
+
end
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
This omits content-based ETags and, with the default timestamp-validation setting, delegates conditional handling entirely to Rack. `static_cache_control` still applies when configured. Template responses and downstream applications are unaffected by this option.
|
|
20
|
+
|
|
21
|
+
### Optional timestamp-validation opt-out
|
|
22
|
+
|
|
23
|
+
`static_timestamps` defaults to `true`, preserving Rack's timestamp-only conditional responses. Set `config.static_timestamps = false` to ignore `If-Modified-Since` on static requests when modification times are unreliable. The `Last-Modified` response header is still emitted, and matching ETags can still produce a `304`. The switches are independent: set both `static_etags` and `static_timestamps` to `false` to disable both conditional checks. Neither option affects template responses or downstream applications.
|