universal_renderer 0.5.2 → 0.8.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.
@@ -1,61 +1,150 @@
1
+ require "active_support/core_ext/object/blank"
1
2
  require "loofah"
2
3
 
3
4
  module UniversalRenderer
4
5
  module SSR
6
+ # Removes executable content from HTML returned by the SSR service while
7
+ # preserving the elements and data attributes needed to hydrate an app.
8
+ #
9
+ # A blocklist over the whole HTML grammar cannot be a boundary against
10
+ # attacker-controlled markup, because the sanitizer and the browser have to
11
+ # agree on how the document parses. Treat it as defense in depth over HTML
12
+ # your own renderer produced.
5
13
  class Scrubber < ::Loofah::Scrubber
14
+ # Elements that change how the *rest* of the markup is tokenized, so the
15
+ # tree this scrubber inspects is not the tree the browser builds.
16
+ #
17
+ # `<noscript>` is raw text with scripting enabled (the browser) and markup
18
+ # without it (the sanitizer), so `<noscript><p title="</noscript><img src=x
19
+ # onerror=...>">` reaches the browser as a live element. The MathML three
20
+ # flip the parser between foreign content and HTML integration points for
21
+ # the same effect. None belong in a server render.
22
+ PARSER_CONTEXT_ELEMENTS = %w[
23
+ noscript mglyph malignmark annotation-xml
24
+ ].freeze
25
+
26
+ BLOCKED_ELEMENTS = (
27
+ %w[
28
+ base embed frame frameset iframe object script
29
+ animate animatemotion animatetransform set
30
+ ] + PARSER_CONTEXT_ELEMENTS
31
+ ).freeze
32
+ # Non-executable data-script MIME types. HTML treats a script whose type is
33
+ # neither a JavaScript MIME type nor one of the special types (`module`,
34
+ # `importmap`, `speculationrules`) as an inert data block.
35
+ #
36
+ # The exception exists for JSON-LD, which the render emits and which would
37
+ # otherwise be sanitized away along with the SEO that motivates SSR.
38
+ ALLOWED_SCRIPT_TYPES = %w[application/json application/ld+json].freeze
39
+ URI_ATTRIBUTES = %w[
40
+ action background cite codebase data formaction href longdesc poster src
41
+ srcset xlink:href
42
+ ].freeze
43
+ ALLOWED_PROTOCOLS = %w[http https mailto tel].freeze
44
+ DANGEROUS_PROTOCOL = /\A(?:javascript|vbscript):/i
45
+ DANGEROUS_DATA = %r{\Adata:(?:text/html|application/xhtml\+xml|image/svg\+xml)}i
46
+ SAFE_DATA_IMAGE = %r{\Adata:image/(?:avif|gif|jpeg|png|webp);base64,}i
47
+ # An SVG referenced by <img> renders in a restricted mode: no scripts, no
48
+ # external references. Bundlers routinely inline icons as data URIs, so the
49
+ # render would otherwise lose them. `<source>` inside `<picture>` feeds the
50
+ # same mode; inside `<video>`/`<audio>` it does not.
51
+ INLINE_SVG_DATA = %r{\Adata:image/svg\+xml[,;]}i
52
+ IMAGE_SOURCE_ATTRIBUTES = %w[src srcset].freeze
53
+
6
54
  def initialize
7
55
  super
8
56
  @direction = :top_down
9
57
  end
10
58
 
11
59
  def scrub(node)
12
- # Primary actions: stop if script, continue if a passthrough tag, otherwise clean attributes.
13
- return Loofah::Scrubber::STOP if handle_script_node(node) # Checks for <script> and removes it
60
+ return Loofah::Scrubber::CONTINUE unless node.element?
14
61
 
15
- # Allows <link rel="stylesheet">, <style>, <meta> to pass through this scrubber.
16
- return Loofah::Scrubber::CONTINUE if passthrough_node?(node)
62
+ if blocked_element?(node) || refreshing_meta?(node)
63
+ node.remove
64
+ return Loofah::Scrubber::STOP
65
+ end
17
66
 
18
- # For all other nodes, clean potentially harmful attributes.
19
67
  clean_attributes(node)
20
- # Default Loofah behavior (CONTINUE for children) applies if not returned earlier.
68
+ Loofah::Scrubber::CONTINUE
21
69
  end
22
70
 
23
71
  private
24
72
 
25
- # Handles <script> tags: removes them and returns true if a script node was processed.
26
- def handle_script_node(node)
27
- return false unless node.name == "script"
73
+ def blocked_element?(node)
74
+ return false if node.name.downcase == "script" && data_script?(node)
28
75
 
29
- node.remove
30
- true # Indicates the node was a script and has been handled.
76
+ BLOCKED_ELEMENTS.include?(node.name.downcase)
31
77
  end
32
78
 
33
- # Checks if the node is a type that should bypass detailed attribute scrubbing.
34
- def passthrough_node?(node)
35
- (node.name == "link" && node["rel"]&.to_s&.downcase == "stylesheet") ||
36
- %w[style meta].include?(node.name)
79
+ # Scripts with no explicit type are JavaScript, so they stay blocked.
80
+ def data_script?(node)
81
+ type = node["type"].to_s.downcase.strip
82
+ return false if type.blank?
83
+
84
+ ALLOWED_SCRIPT_TYPES.include?(type.split(";", 2).first.strip)
37
85
  end
38
86
 
39
- # Orchestrates the cleaning of attributes for a given node.
87
+ def refreshing_meta?(node)
88
+ node.name.downcase == "meta" &&
89
+ node["http-equiv"]&.strip&.casecmp?("refresh")
90
+ end
91
+
92
+ # Attribute *nodes*, not the `attributes` hash: that hash is keyed by local
93
+ # name, so under the HTML5 parser `xlink:href` arrives as `"href"` and
94
+ # `node["href"]` returns nil. An empty value read as safe, which left
95
+ # `<svg><a xlink:href="javascript:...">` intact.
40
96
  def clean_attributes(node)
41
- remove_javascript_href(node)
42
- remove_event_handlers(node)
97
+ node.attribute_nodes.each do |attribute|
98
+ normalized_name = qualified_name(attribute)
99
+ remove_attribute =
100
+ normalized_name.start_with?("on") ||
101
+ normalized_name == "srcdoc" ||
102
+ (URI_ATTRIBUTES.include?(normalized_name) &&
103
+ unsafe_uri?(attribute.value.to_s, normalized_name, node))
104
+
105
+ attribute.remove if remove_attribute
106
+ end
43
107
  end
44
108
 
45
- # Removes "javascript:" hrefs from <a> tags.
46
- def remove_javascript_href(node)
47
- return unless node.name == "a" && node["href"]
48
- href = node["href"].to_s.downcase
49
- node.remove_attribute("href") if href.start_with?("javascript:")
109
+ # The name as written in the markup. HTML4 keeps the prefix in the name;
110
+ # HTML5 splits it into a namespace.
111
+ def qualified_name(attribute)
112
+ prefix = attribute.namespace&.prefix
113
+ name = attribute.name.to_s
114
+ (prefix ? "#{prefix}:#{name}" : name).downcase
115
+ end
116
+
117
+ # The parser has already resolved character references, so `value` is literal
118
+ # text. Decoding it again would only corrupt URLs that legitimately contain
119
+ # an escaped entity.
120
+ def unsafe_uri?(value, attribute_name, node)
121
+ normalized = value.gsub(/[\u0000-\u0020]/, "")
122
+ return true if normalized.match?(DANGEROUS_PROTOCOL)
123
+ return false if inline_svg_image?(normalized, attribute_name, node)
124
+ return true if normalized.match?(DANGEROUS_DATA)
125
+
126
+ scheme = normalized[/\A([a-z][a-z0-9+.-]*):/i, 1]
127
+ return false unless scheme
128
+ return false if ALLOWED_PROTOCOLS.include?(scheme.downcase)
129
+ return false if %w[src srcset].include?(attribute_name) &&
130
+ normalized.match?(SAFE_DATA_IMAGE)
131
+
132
+ true
133
+ end
134
+
135
+ def inline_svg_image?(uri, attribute_name, node)
136
+ return false unless IMAGE_SOURCE_ATTRIBUTES.include?(attribute_name)
137
+ return false unless restricted_image_context?(node)
138
+
139
+ uri.match?(INLINE_SVG_DATA)
50
140
  end
51
141
 
52
- # Removes "on*" event handler attributes from any node.
53
- def remove_event_handlers(node)
54
- attrs_to_remove =
55
- node.attributes.keys.select do |name|
56
- name.to_s.downcase.start_with?("on")
57
- end
58
- attrs_to_remove.each { |attr_name| node.remove_attribute(attr_name) }
142
+ def restricted_image_context?(node)
143
+ case node.name.downcase
144
+ when "img" then true
145
+ when "source" then node.parent&.name&.downcase == "picture"
146
+ else false
147
+ end
59
148
  end
60
149
  end
61
150
  end
@@ -0,0 +1,243 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "net/http"
4
+
5
+ module UniversalRenderer
6
+ # Runs the SSR renderer as a child process and keeps it running. Used by the
7
+ # Puma plugin; not public API.
8
+ #
9
+ # The renderer must not take the app server down with it: when it is gone,
10
+ # Rails falls back to client rendering, a degraded page rather than an outage.
11
+ # Nothing else notices that either, so this restarts it when it exits, and
12
+ # when it is alive but stops answering its health endpoint (a render that never
13
+ # settles holds its concurrency slot forever, see "Render timeout and health").
14
+ #
15
+ # Plain Ruby with no Rails dependency: the Puma plugin runs it in the Puma
16
+ # master, which may not have loaded the app.
17
+ class Supervisor # rubocop:disable Metrics/ClassLength -- one process lifecycle; the threads share its state
18
+ LOG_PREFIX = "[universal_renderer]"
19
+ HEALTH_PATH = "/health"
20
+ EXIT_POLL_INTERVAL = 0.2
21
+ # A renderer that keeps dying waits 1, 2, 4 ... up to this many seconds.
22
+ MAX_BACKOFF = 30
23
+ # A renderer that ran this long was healthy, so its next restart waits 1s again.
24
+ HEALTHY_AFTER = 60
25
+
26
+ attr_reader :pid
27
+
28
+ # @param command [Array<String>] Renderer command line, run without a shell.
29
+ # @param port [Integer] Passed to the renderer as `SSR_PORT`, and used for health checks.
30
+ # @param health_interval [Numeric, nil] Seconds between health checks; `nil` turns them off.
31
+ # @param health_failures [Integer] Failed checks in a row before a restart.
32
+ # @param stop_timeout [Numeric] Seconds to wait after `TERM` before `KILL`.
33
+ def initialize(command:, port:, # rubocop:disable Metrics/ParameterLists -- the timings exist for tests
34
+ env: {}, health_interval: 10, health_failures: 3, stop_timeout: 10,
35
+ logger: ->(message) { warn(message) })
36
+ @command = command
37
+ @port = Integer(port)
38
+ @env = env.merge("SSR_PORT" => @port.to_s)
39
+ @health_interval = health_interval
40
+ @health_failures = health_failures
41
+ @stop_timeout = stop_timeout
42
+ @logger = logger
43
+
44
+ @mutex = Mutex.new
45
+ @exited = ConditionVariable.new
46
+ # Closing it wakes every interruptible sleep at once, for `stop`.
47
+ @wakeup = Queue.new
48
+ @stopping = false
49
+ @planned_exits = Set.new
50
+ end
51
+
52
+ def start
53
+ @supervisor_thread = Thread.new { supervise }
54
+ @health_thread = Thread.new { watch_health } if @health_interval
55
+ self
56
+ end
57
+
58
+ # Replaces the running renderer. Waits for it to exit, so its port is free
59
+ # when this returns; the supervisor starts the next one after one second.
60
+ def restart(reason:)
61
+ outside_trap { terminate(pid, reason) }
62
+ end
63
+
64
+ # Stops the renderer for good and waits for it to exit.
65
+ def stop
66
+ outside_trap do
67
+ # No renderer starts after this, so the one terminated below is the last.
68
+ @mutex.synchronize { @stopping = true }
69
+ @wakeup.close
70
+ terminate(pid, "stopping")
71
+ @supervisor_thread&.join(@stop_timeout)
72
+ @health_thread&.join(1)
73
+ end
74
+ end
75
+
76
+ def stopping?
77
+ @mutex.synchronize { @stopping }
78
+ end
79
+
80
+ private
81
+
82
+ def supervise
83
+ backoff = 1
84
+
85
+ until stopping?
86
+ started_at = monotonic_now
87
+ pid = spawn_renderer
88
+ status = pid && wait_for_renderer(pid)
89
+ planned =
90
+ @mutex.synchronize do
91
+ @pid = nil
92
+ @exited.broadcast
93
+ @planned_exits.delete?(pid)
94
+ end
95
+ break if stopping?
96
+
97
+ # Backing off is for a renderer that keeps dying, not one we replaced.
98
+ backoff = 1 if planned || monotonic_now - started_at >= HEALTHY_AFTER
99
+ log("#{describe_exit(pid, status)}, restarting in #{backoff}s")
100
+ sleep_unless_stopped(backoff)
101
+ backoff = [backoff * 2, MAX_BACKOFF].min
102
+ end
103
+ rescue StandardError => e
104
+ log("supervisor stopped unexpectedly: #{e.class}: #{e.message}")
105
+ end
106
+
107
+ # Spawns under the lock that `stop` takes, so a renderer cannot start after
108
+ # `stop` has looked for the one to terminate.
109
+ def spawn_renderer
110
+ pid =
111
+ @mutex.synchronize do
112
+ next if @stopping
113
+
114
+ @pid = Process.spawn(@env, *@command, pgroup: true)
115
+ end
116
+ log("renderer started (pid=#{pid}, port=#{@port})") if pid
117
+ pid
118
+ rescue SystemCallError => e
119
+ log("could not start #{@command.first}: #{e.message}")
120
+ nil
121
+ end
122
+
123
+ # Polls instead of blocking in `wait2`: a clustered Puma master reaps every
124
+ # child with `Process.wait2(-1)`, so it may collect the renderer's status first.
125
+ def wait_for_renderer(target)
126
+ loop do
127
+ _, status = Process.wait2(target, Process::WNOHANG)
128
+ return status if status
129
+
130
+ sleep(EXIT_POLL_INTERVAL)
131
+ end
132
+ rescue Errno::ECHILD
133
+ nil
134
+ end
135
+
136
+ def describe_exit(target, status)
137
+ return "renderer failed to start" unless target
138
+ return "renderer pid=#{target} exited (reaped by the app server)" unless status
139
+
140
+ "renderer pid=#{target} exited (#{status})"
141
+ end
142
+
143
+ # A renderer can be alive and still useless: a wedged render, a blocked event
144
+ # loop. Waiting for it to exit would wait forever, so replace it.
145
+ def watch_health
146
+ strikes = 0
147
+ watched_pid = nil
148
+
149
+ until stopping?
150
+ sleep_unless_stopped(@health_interval)
151
+ current_pid = pid
152
+ if current_pid != watched_pid
153
+ watched_pid = current_pid
154
+ strikes = 0
155
+ end
156
+ next if current_pid.nil?
157
+
158
+ if healthy?
159
+ strikes = 0
160
+ next
161
+ end
162
+
163
+ strikes += 1
164
+ next if strikes < @health_failures
165
+
166
+ # A failure, not a planned restart: a renderer that keeps wedging backs off.
167
+ terminate(current_pid, "failed #{strikes} health checks", planned: false)
168
+ strikes = 0
169
+ end
170
+ rescue StandardError => e
171
+ log("health checks stopped unexpectedly: #{e.class}: #{e.message}")
172
+ end
173
+
174
+ def healthy?
175
+ Net::HTTP.start("127.0.0.1", @port, open_timeout: 1, read_timeout: 5) do |http|
176
+ http.get(HEALTH_PATH).is_a?(Net::HTTPSuccess)
177
+ end
178
+ rescue StandardError
179
+ false
180
+ end
181
+
182
+ # Acts only while `target` is still the running renderer: a health check can
183
+ # take seconds, and the renderer it judged may have been replaced meanwhile.
184
+ # A planned exit restarts after one second instead of continuing the backoff.
185
+ def terminate(target, reason, planned: true)
186
+ current =
187
+ @mutex.synchronize do
188
+ next false unless target && @pid == target
189
+
190
+ @planned_exits << target if planned
191
+ true
192
+ end
193
+ return unless current
194
+
195
+ log("stopping renderer pid=#{target} (#{reason})")
196
+ signal(target, "TERM")
197
+ return if wait_for_exit(target, @stop_timeout)
198
+
199
+ log("renderer pid=#{target} did not exit within #{@stop_timeout}s, killing it")
200
+ signal(target, "KILL")
201
+ wait_for_exit(target, 2)
202
+ end
203
+
204
+ # The renderer runs in its own process group, so this also reaches anything
205
+ # it started (a wrapper script, a `node` behind `npx`).
206
+ def signal(target, name)
207
+ Process.kill(name, -target)
208
+ rescue Errno::ESRCH, Errno::EPERM
209
+ nil
210
+ end
211
+
212
+ def wait_for_exit(target, timeout)
213
+ deadline = monotonic_now + timeout
214
+ @mutex.synchronize do
215
+ while @pid == target
216
+ remaining = deadline - monotonic_now
217
+ return false if remaining <= 0
218
+
219
+ @exited.wait(@mutex, remaining)
220
+ end
221
+ end
222
+ true
223
+ end
224
+
225
+ # Puma runs some lifecycle hooks inside its signal handlers, where
226
+ # `Mutex#synchronize` raises ThreadError. A new thread is not in trap context.
227
+ def outside_trap(&)
228
+ Thread.new(&).join
229
+ end
230
+
231
+ def sleep_unless_stopped(seconds)
232
+ @wakeup.pop(timeout: seconds)
233
+ end
234
+
235
+ def log(message)
236
+ @logger.call("#{LOG_PREFIX} #{message}")
237
+ end
238
+
239
+ def monotonic_now
240
+ Process.clock_gettime(Process::CLOCK_MONOTONIC)
241
+ end
242
+ end
243
+ end
@@ -1,3 +1,3 @@
1
1
  module UniversalRenderer
2
- VERSION = "0.5.2".freeze
2
+ VERSION = "0.8.0".freeze
3
3
  end
@@ -1,5 +1,6 @@
1
1
  require "universal_renderer/version"
2
2
  require "universal_renderer/configuration"
3
+ require "universal_renderer/instrumentation"
3
4
  require "universal_renderer/ssr/helpers"
4
5
  require "universal_renderer/renderable"
5
6
  require "universal_renderer/engine"
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: universal_renderer
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.5.2
4
+ version: 0.8.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - thaske
@@ -70,6 +70,13 @@ files:
70
70
  - Rakefile
71
71
  - lib/generators/universal_renderer/install_generator.rb
72
72
  - lib/generators/universal_renderer/templates/initializer.rb
73
+ - lib/generators/universal_renderer/templates/ssr.rake
74
+ - lib/generators/universal_renderer/templates/ssr/config.ts
75
+ - lib/generators/universal_renderer/templates/ssr/dev.ts
76
+ - lib/generators/universal_renderer/templates/ssr/globals.ts
77
+ - lib/generators/universal_renderer/templates/ssr/server.ts
78
+ - lib/generators/universal_renderer/templates/vite.config.ssr.mts
79
+ - lib/puma/plugin/universal_renderer.rb
73
80
  - lib/tasks/universal_renderer_tasks.rake
74
81
  - lib/universal_renderer.rb
75
82
  - lib/universal_renderer/client/base.rb
@@ -80,11 +87,13 @@ files:
80
87
  - lib/universal_renderer/client/stream/setup.rb
81
88
  - lib/universal_renderer/configuration.rb
82
89
  - lib/universal_renderer/engine.rb
90
+ - lib/universal_renderer/instrumentation.rb
83
91
  - lib/universal_renderer/renderable.rb
84
92
  - lib/universal_renderer/ssr/helpers.rb
85
93
  - lib/universal_renderer/ssr/placeholders.rb
86
94
  - lib/universal_renderer/ssr/response.rb
87
95
  - lib/universal_renderer/ssr/scrubber.rb
96
+ - lib/universal_renderer/supervisor.rb
88
97
  - lib/universal_renderer/version.rb
89
98
  homepage: https://github.com/thaske/universal_renderer
90
99
  licenses: