Class: Tina4::Frond

Inherits:
Object
  • Object
show all
Defined in:
lib/tina4/frond.rb

Defined Under Namespace

Classes: LoopContext

Constant Summary collapse

TEXT =

-- Token types ----------------------------------------------------------

:text
VAR =

... }

:var
BLOCK =

... %

:block
COMMENT =

... #

:comment
TOKEN_RE =

Regex to split template source into tokens

/(\{%-?\s*.*?\s*-?%\})|(\{\{-?\s*.*?\s*-?\}\})|(\{#.*?#\})/m
HTML_ESCAPE_MAP =

HTML escape table

{ "&" => "&amp;", "<" => "&lt;", ">" => "&gt;",
'"' => "&quot;", "'" => "&#39;" }.freeze
HTML_ESCAPE_RE = 
/[&<>"']/
EXTENDS_RE =

-- Compiled regex constants (optimization: avoid re-compiling in methods) --

/\{%-?\s*extends\s+["'](.+?)["']\s*-?%\}/
BLOCK_RE = 
/\{%-?\s*block\s+(\w+)\s*-?%\}(.*?)\{%-?\s*endblock\s*-?%\}/m
STRING_LIT_RE = 
/\A["'](.*)["']\z/
INTEGER_RE = 
/\A-?\d+\z/
FLOAT_RE = 
/\A-?\d+\.\d+\z/
ARRAY_LIT_RE = 
/\A\[(.+)\]\z/m
HASH_LIT_RE = 
/\A\{(.+)\}\z/m
HASH_PAIR_RE = 
/\A\s*(?:["']([^"']+)["']|(\w+))\s*:\s*(.+)\z/
RANGE_LIT_RE = 
/\A(\d+)\.\.(\d+)\z/
ARITHMETIC_OPS = 
[" + ", " - ", " * ", " // ", " / ", " % ", " ** "].freeze
LOOSER_THAN_PIPE_OPS =

Operators Twig binds LOOSER than the filter pipe |. When one of these sits at the top level alongside a pipe (e.g. amount|number_format(2) ~ ' EUR'), the whole expression must go through eval_expr (which resolves the pipe at its correct, tighter precedence) instead of being split on the pipe as a plain filter chain. Detection is quote/paren-aware (find_outside_quotes) so operator-like text inside a string or filter args never false-triggers.

[
  "~", "??", " if ",
  " not in ", " in ", " is not ", " is ", "!=", "==", ">=", "<=", ">", "<",
  " and ", " or ", " not ",
  " + ", " - ", " * ", " // ", " / ", " % ", " ** "
].freeze
FUNC_CALL_RE =

A dot is allowed in the callee so import "f" as m % can register its macros under the literal key "m.greet" and m.greet("Andre") } resolves as a call. Without the dot the whole expression was not recognised as a function call at all, so an aliased macro rendered as SILENTLY EMPTY.

/\A([\w.]+)\s*\((.*)\)\z/m
FILTER_WITH_ARGS_RE = 
/\A(\w+)\s*\((.*)\)\z/m
FILTER_CMP_RE = 
/\A(\w+)\s*(!=|==|>=|<=|>|<)\s*(.+)\z/
OR_SPLIT_RE = 
/\s+or\s+/
AND_SPLIT_RE = 
/\s+and\s+/
IS_NOT_RE = 
/\A(.+?)\s+is\s+not\s+(\w+)(.*)\z/
IS_RE = 
/\A(.+?)\s+is\s+(\w+)(.*)\z/
NOT_IN_RE = 
/\A(.+?)\s+not\s+in\s+(.+)\z/
IN_RE = 
/\A(.+?)\s+in\s+(.+)\z/
DIVISIBLE_BY_RE = 
/\s*by\s*\(\s*(\d+)\s*\)/
RESOLVE_SPLIT_RE = 
/\.|\[([^\]]+)\]/
RESOLVE_STRIP_RE = 
/\A["']|["']\z/
DIGIT_RE = 
/\A\d+\z/
FOR_RE = 
/\Afor\s+(\w+)(?:\s*,\s*(\w+))?\s+in\s+(.+)\z/
SET_RE = 
/\Aset\s+(\w+)\s*=\s*(.+)\z/m
INCLUDE_RE = 
/\Ainclude\s+["'](.+?)["'](?:\s+with\s+(.+))?\z/
MACRO_RE = 
/\Amacro\s+(\w+)\s*\(([^)]*)\)/
LIVE_RE =

live "name" poll N | sse | ws "path" [src "url"] %

/\Alive\s+["']([^"']+)["'](.*)\z/m
LIVE_WS_RE = 
/ws\s+["']([^"']+)["']/
LIVE_SRC_RE = 
/src\s+["']([^"']+)["']/
FROM_IMPORT_RE = 
/\Afrom\s+["'](.+?)["']\s+import\s+(.+)/
IMPORT_AS_RE = 
/\Aimport\s+["'](.+?)["']\s+as\s+(\w+)/
CACHE_RE = 
/\Acache\s+["'](.+?)["']\s*(\d+)?/
SPACELESS_RE = 
/>\s+</
AUTOESCAPE_RE = 
/\Aautoescape\s+(false|true)/
STRIPTAGS_RE = 
/<[^>]+>/
THOUSANDS_RE = 
/(\d)(?=(\d{3})+(?!\d))/
SLUG_CLEAN_RE = 
/[^a-z0-9]+/
SLUG_TRIM_RE = 
/\A-|-\z/
INLINE_FILTERS =

Set of common no-arg filter names that can be inlined for speed

%w[upper lower length trim capitalize title string int escape e].each_with_object({}) { |f, h| h[f] = true }.freeze
TEMPLATE_CACHE_MAX =

Hard cap on the template caches — @compiled and @compiled_strings (ADR-0004, parity with PHP/Python/Node TEMPLATE_CACHE_MAX).

An entry here is a whole token list, so the cap sits well below what a per-expression memo would justify. 256 is far above any real application's template count, so a normal app never evicts. The cap exists for the workload that genuinely grows without limit for the life of a worker: render_string keys on md5(source), so an app that builds template strings dynamically adds an entry per distinct string.

256
@@class_filters =

-- Class-level registries ------------------------------------------------ Persist globals, filters, and tests across hot-reloads and across module boundaries. When app.rb does Tina4::Frond.add_filter("money") { ... } at startup before any instance exists, the registration sits here. Every subsequent Tina4::Frond.new drains these into its instance-local registries — so hot-reloads (which re-execute frond = Frond.new) and late-constructed engines automatically inherit prior registrations.

The same-name dual-callable (class + instance) methods below let callers write either Tina4::Frond.add_filter(...) (class-level only) or frond.add_filter(...) (updates both the class registry and the instance's live filter map). Parity with tina4-python's _ClassOrInstanceMethod descriptor.

{}
@@class_globals = 
{}
@@class_tests = 
{}
@@class_live_fragments =

-- Live-block registries (server-rendered live % regions) ----------- A live % block registers three things when its page first renders:

* class_live_fragments[name]  -> the raw body source, re-rendered on
                               every refresh by the /__frond/live/<name>
                               endpoint or push_live
* class_live_sources[name]    -> an optional data provider (live_source)
                               that re-runs with the LIVE request each
                               refresh, so auth re-applies (IDOR guard)
* class_live_ws_paths[name]   -> the ws path a `ws "path"` block declared,
                               used as the push_live broadcast target

These persist across requests in the long-lived server (parity with the Python master's class-level dicts and PHP's static registries).

{}
@@class_live_sources = 
{}
@@class_live_ws_paths = 
{}

Class Attribute Summary collapse

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(template_dir: "src/templates") ⇒ Frond

Returns a new instance of Frond.



247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
 
# File 'lib/tina4/frond.rb', line 247

def initialize(template_dir: "src/templates")
  @template_dir    = template_dir
  @filters         = default_filters
  @globals         = {}
  @tests           = default_tests
  @auto_escape     = true

  # Sandboxing
  @sandbox         = false
  @allowed_filters = nil
  @allowed_tags    = nil
  @allowed_vars    = nil

  # Fragment cache: key => [html, expires_at]
  @fragment_cache  = {}

  # Token pre-compilation cache
  @compiled         = {}  # {template_name => [tokens, mtime]}
  @compiled_strings = {}  # {md5_hash => tokens}

  # Parsed filter chain cache: expr_string => [variable, filters]
  @filter_chain_cache = {}

  # Resolved dotted-path split cache: expr_string => parts_array
  @resolve_cache = {}

  # Sandbox root-var split cache: var_name => root_var_string
  @dotted_split_cache = {}

  # Built-in global functions
  register_builtin_globals

  # Drain class-level registries into this instance. Filters and tests
  # registered via ``Tina4::Frond.add_filter`` BEFORE this instance was
  # constructed flow in here. Globals likewise. This is the key to the
  # static-facade: ``app.rb`` registers once at startup, and every
  # Frond instance created later (including those born from hot-reloads)
  # automatically inherits the registration. Parity with tina4-python.
  @filters.merge!(@@class_filters)
  @globals.merge!(@@class_globals)
  @tests.merge!(@@class_tests)
end

Class Attribute Details

.form_token_session_id ⇒ Object

Returns the value of attribute form_token_session_id.



2635
2636
2637
 
# File 'lib/tina4/frond.rb', line 2635

def form_token_session_id
  @form_token_session_id
end

Instance Attribute Details

#template_dir ⇒ Object (readonly)

Public API



245
246
247
 
# File 'lib/tina4/frond.rb', line 245

def template_dir
  @template_dir
end

Class Method Details

.add_filter(name, &blk) ⇒ Object

Register a custom filter on the class registry only.

Callable as Tina4::Frond.add_filter("money") { |v| ... } at app startup BEFORE any instance exists. The registration is remembered at class level so every later Tina4::Frond.new inherits it. To also update a live instance's filter map, use the instance method form.



358
359
360
 
# File 'lib/tina4/frond.rb', line 358

def self.add_filter(name, &blk)
  @@class_filters[name.to_s] = blk
end

.add_global(name, value) ⇒ Object

Register a global variable on the class registry only.

Same dual-callable semantics as add_filter — see that method for the static-facade pattern.



374
375
376
 
# File 'lib/tina4/frond.rb', line 374

def self.add_global(name, value)
  @@class_globals[name.to_s] = value
end

.add_test(name, &blk) ⇒ Object

Register a custom test on the class registry only.

Same dual-callable semantics as add_filter — see that method for the static-facade pattern.



366
367
368
 
# File 'lib/tina4/frond.rb', line 366

def self.add_test(name, &blk)
  @@class_tests[name.to_s] = blk
end

.clear_registry ⇒ Object

Clear the class-level globals/filters/tests/live registries.

Useful in test fixtures to prevent leaking state between tests. Does NOT affect built-in filters or globals — only user-registered ones.



62
63
64
65
66
67
68
69
 
# File 'lib/tina4/frond.rb', line 62

def self.clear_registry
  @@class_filters = {}
  @@class_globals = {}
  @@class_tests   = {}
  @@class_live_fragments = {}
  @@class_live_sources   = {}
  @@class_live_ws_paths  = {}
end

.escape_html(str) ⇒ Object

Utility: HTML escape



428
429
430
 
# File 'lib/tina4/frond.rb', line 428

def self.escape_html(str)
  str.to_s.gsub(HTML_ESCAPE_RE, HTML_ESCAPE_MAP)
end

.generate_form_jwt(descriptor = "") ⇒ String

Generate a raw JWT form token string.

Parameters:

  • descriptor (String) (defaults to: "") —

    Optional string to enrich the token payload.

    • Empty: payload is => "form"
    • "admin_panel": payload is => "form", "context" => "admin_panel"
    • "checkout|order_123": payload is => "form", "context" => "checkout", "ref" => "order_123"

Returns:

  • (String) —

    The raw JWT token string.



2654
2655
2656
2657
2658
2659
2660
2661
2662
2663
2664
2665
2666
2667
2668
2669
2670
2671
2672
2673
2674
2675
2676
 
# File 'lib/tina4/frond.rb', line 2654

def self.generate_form_jwt(descriptor = "")
  require_relative "log"
  require_relative "auth"

  payload = { "type" => "form", "nonce" => SecureRandom.hex(8) }
  if descriptor && !descriptor.empty?
    if descriptor.include?("|")
      parts = descriptor.split("|", 2)
      payload["context"] = parts[0]
      payload["ref"] = parts[1]
    else
      payload["context"] = descriptor
    end
  end

  # Include session_id for CSRF session binding
  sid = form_token_session_id.to_s
  payload["session_id"] = sid unless sid.empty?

  ttl_minutes = (ENV["TINA4_TOKEN_LIMIT"] || "60").to_i
  expires_in = ttl_minutes * 60
  Tina4::Auth.create_token(payload, expires_in: expires_in)
end

.generate_form_token(descriptor = "") ⇒ Object 



2678
2679
2680
2681
 
# File 'lib/tina4/frond.rb', line 2678

def self.generate_form_token(descriptor = "")
  token = generate_form_jwt(descriptor)
  Tina4::SafeString.new(%(<input type="hidden" name="formToken" value="#{CGI.escapeHTML(token)}">))
end

.generate_form_token_value(descriptor = "") ⇒ Object

Return just the raw JWT form token string (no wrapper). Registered as both formTokenValue and form_token_value template globals.



2685
2686
2687
 
# File 'lib/tina4/frond.rb', line 2685

def self.generate_form_token_value(descriptor = "")
  Tina4::SafeString.new(generate_form_jwt(descriptor))
end

.get_live_source(name) ⇒ Object

The provider registered for a live block, or nil.



2212
2213
2214
 
# File 'lib/tina4/frond.rb', line 2212

def self.get_live_source(name)
  @@class_live_sources[name]
end

.get_live_ws_path(name) ⇒ Object

The ws path a live block declared (data-ws), or nil.



2222
2223
2224
 
# File 'lib/tina4/frond.rb', line 2222

def self.get_live_ws_path(name)
  @@class_live_ws_paths[name]
end

.has_live_fragment?(name) ⇒ Boolean

Whether a live fragment has been registered (its page rendered).

Returns:

  • (Boolean) 


2217
2218
2219
 
# File 'lib/tina4/frond.rb', line 2217

def self.has_live_fragment?(name)
  @@class_live_fragments.key?(name)
end

.live_attr(value) ⇒ Object

Escape a value for use inside an HTML attribute on a live marker. Byte-identical order to the Python master / PHP liveAttr so the emitted marker element matches across all four frameworks.



138
139
140
141
 
# File 'lib/tina4/frond.rb', line 138

def self.live_attr(value)
  value.to_s.gsub("&", "&amp;").gsub('"', "&quot;")
       .gsub("<", "&lt;").gsub(">", "&gt;")
end

.live_source(name, callable = nil, &blk) ⇒ Object

Register a data provider for a live % block. Accepts a block OR a callable (proc/lambda); it is invoked with the live request on every refresh so auth re-applies (IDOR guard). Mirrors Python's @live_source.



2207
2208
2209
 
# File 'lib/tina4/frond.rb', line 2207

def self.live_source(name, callable = nil, &blk)
  @@class_live_sources[name] = callable || blk
end

.push_live(name, data = {}) ⇒ Object

Re-render the '' live fragment and push it to connected clients. Broadcasts a type,name,html envelope over WebSocket to the block's declared data-ws path (else a room named ). Returns the rendered HTML, or nil if the fragment is not registered. Mirrors Python push_live / PHP pushLive. The broadcast is best-effort — a missing/failed WS engine never raises into the caller.



2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
 
# File 'lib/tina4/frond.rb', line 2254

def self.push_live(name, data = {})
  html = render_live(name, data)
  return nil if html.nil?

  envelope = { "type" => "live", "name" => name, "html" => html }.to_json
  engine = (Tina4::WebSocket.current if defined?(Tina4::WebSocket))
  if engine
    begin
      ws_path = get_live_ws_path(name)
      if ws_path
        engine.broadcast(envelope, path: ws_path)
      else
        engine.broadcast_to_room(name, envelope)
      end
    rescue StandardError => e
      Tina4::Log.error("push_live(#{name}) broadcast failed: #{e.message}") if defined?(Tina4::Log)
    end
  end
  html
end

.register_live_endpoint! ⇒ Object

Register the always-on GET /__frond/live/name endpoint that re-renders a live block on demand. Idempotent — guarded against a re-register after a Router.clear! (specs / hot-reload rescans). Mirrors PHP App::registerLiveEndpoint.



2278
2279
2280
2281
2282
2283
2284
2285
 
# File 'lib/tina4/frond.rb', line 2278

def self.register_live_endpoint!
  return if Tina4::Router.find_route("GET", "/__frond/live/live-probe")

  Tina4::Router.add(
    "GET", "/__frond/live/{name}",
    lambda { |request, response, name| Tina4::Frond.respond_live(request, response, name) }
  )
end

.render_dump(value) ⇒ Object

Render a value as a pre-formatted inspect() wrapped in 

 tags.


Gated on TINA4_DEBUG=true. In production (TINA4_DEBUG unset or false)
this returns an empty SafeString to avoid leaking internal state,
object shapes, or sensitive values into rendered HTML.


Shared by the {{ value|dump }} filter and the {{ dump(value) }}
global function so both produce identical output and obey the same
gating.


  


2610
2611
2612
2613
2614
2615
2616
2617
2618
2619
2620
 
# File 'lib/tina4/frond.rb', line 2610

def self.render_dump(value)
  return SafeString.new("") unless ENV.fetch("TINA4_DEBUG", "").downcase == "true"

  dumped = value.inspect
  escaped = dumped
    .gsub("&", "&amp;")
    .gsub("<", "&lt;")
    .gsub(">", "&gt;")
    .gsub('"', "&quot;")
  SafeString.new("<pre>#{escaped}</pre>")
end

.render_live(name, data = {}) ⇒ Object

Re-render a registered live % fragment by name with fresh data. Returns the rendered HTML, or nil if no fragment is registered under that name yet (its page has not rendered). The /__frond/live/ endpoint calls this after resolving the provider data.



2197
2198
2199
2200
2201
2202
 
# File 'lib/tina4/frond.rb', line 2197

def self.render_live(name, data = {})
  source = @@class_live_fragments[name]
  return nil if source.nil?

  new.render_string(source, data || {})
end

.respond_live(request, response, name) ⇒ Object

Handle GET /__frond/live/name: resolve the provider, run it with the live request (auth re-applies), re-render the fragment, return via the response callable. 404 for unknown name / unrendered fragment. Mirrors Python's live_endpoint and PHP's respondLive.



2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
 
# File 'lib/tina4/frond.rb', line 2230

def self.respond_live(request, response, name)
  provider = @@class_live_sources[name]
  if !@@class_live_fragments.key?(name) && provider.nil?
    return response.call("live block not found: #{name}", 404)
  end

  context = {}
  unless provider.nil?
    result = provider.call(request)
    context = result.is_a?(Hash) ? result : {}
  end

  html = render_live(name, context)
  return response.call("live fragment not registered yet: #{name}", 404) if html.nil?

  response.call(html)
end

.set_form_token_session_id(session_id) ⇒ Object

Set the session ID used for CSRF form token binding. Parity with Python/PHP/Node: Frond.set_form_token_session_id(id)

Parameters:

  • session_id (String) —

    The session ID to bind form tokens to



2641
2642
2643
 
# File 'lib/tina4/frond.rb', line 2641

def set_form_token_session_id(session_id)
  self.form_token_session_id = session_id
end

Instance Method Details

#add_filter(name, &blk) ⇒ Object

Register a custom filter.

Updates BOTH the class registry (so future Tina4::Frond.new picks the filter up) AND this instance's live filter map (so the change is visible to subsequent renders on the current engine).



383
384
385
386
387
 
# File 'lib/tina4/frond.rb', line 383

def add_filter(name, &blk)
  self.class.add_filter(name, &blk)
  @filters[name.to_s] = blk
  self
end

#add_global(name, value) ⇒ Object

Register a global variable available in all templates.

Updates BOTH the class registry and this instance's live globals map. See add_filter for the dual-write semantics.



403
404
405
406
407
 
# File 'lib/tina4/frond.rb', line 403

def add_global(name, value)
  self.class.add_global(name, value)
  @globals[name.to_s] = value
  self
end

#add_test(name, &blk) ⇒ Object

Register a custom test.

Updates BOTH the class registry and this instance's live tests map. See add_filter for the dual-write semantics.



393
394
395
396
397
 
# File 'lib/tina4/frond.rb', line 393

def add_test(name, &blk)
  self.class.add_test(name, &blk)
  @tests[name.to_s] = blk
  self
end

#clear_cache ⇒ Object

Clear all compiled template caches.



344
345
346
347
348
349
350
 
# File 'lib/tina4/frond.rb', line 344

def clear_cache
  @compiled.clear
  @compiled_strings.clear
  @filter_chain_cache.clear
  @resolve_cache.clear
  @dotted_split_cache.clear
end

#render(template, data = {}) ⇒ Object

Render a template file with data. Uses token caching for performance.

Caching strategy:

* TINA4_DEBUG=true        — never cache (always re-read + re-tokenize).
* TINA4_TEMPLATE_CACHE_TTL > 0 — cache entries expire after N seconds.
* TINA4_TEMPLATE_CACHE_TTL == 0 (default in production) — permanent cache.


296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
 
# File 'lib/tina4/frond.rb', line 296

def render(template, data = {})
  context = @globals.merge(stringify_keys(data))

  path = File.join(@template_dir, template)
  raise "Template not found: #{path}" unless File.exist?(path)

  debug_mode = ENV.fetch("TINA4_DEBUG", "").downcase == "true"
  ttl = (ENV["TINA4_TEMPLATE_CACHE_TTL"] || "0").to_i

  unless debug_mode
    cached = @compiled[template]
    if cached
      # cached layout: [tokens, mtime, cached_at]
      tokens, _mtime, cached_at = cached
      fresh = ttl <= 0 || (Time.now.to_i - cached_at.to_i) < ttl
      return execute_cached(tokens, context) if fresh
    end
  end
  # Dev mode: skip cache entirely — always re-read and re-tokenize
  # so edits to partials and extended base templates are detected

  # Cache miss — load, tokenize, cache
  source = File.read(path, encoding: "utf-8")
  mtime = File.mtime(path)
  tokens = tokenize(source)
  cap_cache(@compiled, TEMPLATE_CACHE_MAX)
  @compiled[template] = [tokens, mtime, Time.now.to_i]
  execute_with_tokens(source, tokens, context)
end

#render_string(source, data = {}) ⇒ Object

Render a template string directly. Uses token caching for performance.



327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
 
# File 'lib/tina4/frond.rb', line 327

def render_string(source, data = {})
  context = @globals.merge(stringify_keys(data))

  key = Digest::MD5.hexdigest(source)
  cached_tokens = @compiled_strings[key]

  if cached_tokens
    return execute_cached(cached_tokens, context)
  end

  tokens = tokenize(source)
  cap_cache(@compiled_strings, TEMPLATE_CACHE_MAX)
  @compiled_strings[key] = tokens
  execute_cached(tokens, context)
end

#sandbox(filters: nil, tags: nil, vars: nil) ⇒ Object

Enable sandbox mode.



410
411
412
413
414
415
416
 
# File 'lib/tina4/frond.rb', line 410

def sandbox(filters: nil, tags: nil, vars: nil)
  @sandbox         = true
  @allowed_filters = filters ? filters.map(&:to_s) : nil
  @allowed_tags    = tags    ? tags.map(&:to_s)    : nil
  @allowed_vars    = vars    ? vars.map(&:to_s)    : nil
  self
end

#unsandbox ⇒ Object

Disable sandbox mode.



419
420
421
422
423
424
425
 
# File 'lib/tina4/frond.rb', line 419

def unsandbox
  @sandbox         = false
  @allowed_filters = nil
  @allowed_tags    = nil
  @allowed_vars    = nil
  self
end