perf: cold-start warm-up, O(1) protected-method gate, schema cache, debug-bar slimming (#3210)

* perf: cold-start warm-up, O(1) protected-method gate, schema cache, debug-bar slimming

Profiling-driven optimizations. JFR + ab profiling showed cold start is ~85%
Lucee CFML->bytecode compilation (bootstrap logic is only ~20ms) while warm
serving is already ~0.4ms; these target the cold path and a couple of clean
hot-path/dev wins, none changing public APIs.

- Dispatch gate (controller/processing.cfc): test the protected-helper set with
  an O(1) StructKeyExists lookup instead of an O(n) ListFindNoCase scan. A
  companion application.wheels.protectedControllerMethodsLookup struct-as-set is
  built once at app start alongside the retained comma-list; case-insensitive
  matching is unchanged.
- Column metadata (databaseAdapters/Base.cfc): memoize cfdbinfo "columns" per
  datasource+table in application.wheels.cache.schema when cacheDatabaseSchema
  is on. Rebuilt on reload, so schema changes are still picked up on reload.
- Dev debug bar (events/onrequestend/debug.cfm): externalize the static CSS/JS
  to vendor/wheels/public/assets/{css,js}/debugbar.* (eliminating the CFML
  ##-escaping footgun) and collapse inter-tag whitespace. Dev-only; production
  unaffected.
- Scaffold (cli templates): ship a /up liveness/warm-up endpoint that
  `wheels deploy`'s healthcheck probes before cutover, plus production-config
  warm-up recipe and inspectTemplate=never guidance.

Signed-off-by: Peter Amiri <petera@pai.com>

* docs(changelog): reference PR #3210 in perf fragments

Signed-off-by: Peter Amiri <petera@pai.com>

* chore(web): refresh visual baseline(s) (all)

Manually triggered baseline refresh via
.github/workflows/refresh-visual-baselines.yml
on branch peter/perf-cold-start-serving-followups.

Run when an intentional content/layout change makes the visual-regression
check fail. The new PNG(s) under web/tests/visual-baselines/ are now the
expected rendering; re-run the failing visual-regression job to flip the
check green.

* fix(model): move schema column cache out of the time-based cache namespace

Addresses the bot reviewer on #3210. The column-metadata cache stored raw
query objects under application.wheels.cache.schema, but every
application.wheels.cache.* category is owned by the time-based cull/count
machinery: $cacheCount() sums StructCount across all categories toward
maximumItemsToCache, and the cull dereferences `.expiresAt` on every entry
with no type guard (Global.cfc:904). A raw query has no expiresAt, so once the
global cache filled (page/partial/query caching, on by default in production)
and a cull was due, it would throw when it reached a schema entry.

- Move the cache to a sibling top-level key application.wheels.schemaColumnCache
  (set in onapplicationstart next to, not under, cache) so the cull/count never
  walk it. Matches the stated intent: persists for the app lifetime, rebuilt on
  reload.
- Mirror $getFromCache's defensive shape: wrap the read in try/catch and
  Duplicate() the cached query on store and on return, so a concurrent struct
  read can't surface a partial value and no caller can mutate the cached query
  in place (the first review's non-blocking note).
- Update schemaColumnCacheSpec and the changelog fragment for the new key.

Signed-off-by: Peter Amiri <petera@pai.com>

---------

Signed-off-by: Peter Amiri <petera@pai.com>
Co-authored-by: Peter Amiri <petera@pai.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Author: 3 people

changelog.d/debugbar-externalized-assets.changed.md

@@ -0,0 +1 @@
+- The development debug bar's static CSS and JavaScript are now maintained as standalone files (`vendor/wheels/public/assets/css/debugbar.css`, `vendor/wheels/public/assets/js/debugbar.js`) and included into the bar, eliminating the CFML `##`-escaped inline blocks (a documented "unescaped `#` crashes the suite" hazard) and trimming the per-response debug payload via inter-tag whitespace collapse. The bar remains development-only and unchanged in production (#3210)

changelog.d/deploy-warmup-up-endpoint.added.md

@@ -0,0 +1 @@
+- New apps scaffolded with `wheels new` now ship a `/up` liveness/warm-up endpoint (`app/controllers/Up.cfc` + route). `wheels deploy`'s proxy healthcheck already probes `/up` before traffic cutover, so the dispatch → controller → render path is compiled on a freshly deployed node before the first real visitor — moving the one-time cold-start compile (the bulk of first-request latency) off user traffic. The production-config guide documents the warm-up recipe and recommends setting the engine's template-inspection mode to `never` in production (#3210)

changelog.d/protected-methods-o1-lookup.performance.md

@@ -0,0 +1 @@
+- The per-request action-dispatch gate now tests the protected-helper list with an O(1) `StructKeyExists` lookup instead of an O(n) `ListFindNoCase` scan over the ~100-250 framework helper names. A companion `application.wheels.protectedControllerMethodsLookup` struct-as-set is built once at application start alongside the existing comma-list (which is retained); case-insensitive matching is unchanged (#3210)

changelog.d/schema-column-cache.performance.md

@@ -0,0 +1 @@
+- Database column metadata is now memoized per datasource+table in `application.wheels.schemaColumnCache` when `cacheDatabaseSchema` is on (the default). Previously every model class init issued a fresh `cfdbinfo type="columns"` JDBC catalog round-trip — a significant first-request cost on remote or wide-schema databases, re-paid on every reload and for every model sharing a table. The cache is rebuilt on reload, so schema changes are still picked up on reload (the same contract as the model and controller config caches) (#3210)

cli/lucli/templates/app/app/controllers/Up.cfc

@@ -0,0 +1,25 @@
+component extends="Controller" {
+
+	/**
+	 * Liveness / warm-up endpoint.
+	 *
+	 * `wheels deploy`'s proxy healthcheck probes `/up` before flipping traffic
+	 * to a freshly deployed node (the default healthcheck path), and load
+	 * balancers can use it as a readiness check. Returning 200 here also
+	 * compiles the dispatch -> controller -> render path on the new host, so the
+	 * first real visitor sees warm latency instead of the one-time first-request
+	 * compile (which is otherwise the bulk of cold-start time).
+	 *
+	 * To warm your hottest ORM metadata too, touch your key models here before
+	 * cutover, e.g.:
+	 *
+	 *   model("Post").count();
+	 *
+	 * Keep this action read-only, cheap, and free of authentication so the probe
+	 * is never blocked.
+	 */
+	function index() {
+		renderText("OK");
+	}
+
+}

cli/lucli/templates/app/config/routes.cfm

@@ -7,6 +7,11 @@
 	mapper()
 		// CLI-Appends-Here
 
+		// Liveness / warm-up endpoint. `wheels deploy`'s proxy healthcheck probes
+		// `/up` before traffic cutover; a 200 here also compiles the request path
+		// so the first real visitor gets warm latency. See app/controllers/Up.cfc.
+		.get(name="up", to="up##index")
+
 		// The "wildcard" call below enables automatic mapping of "controller/action" type routes.
 		// This way you don't need to explicitly add a route every time you create a new action in a controller.
 		.wildcard()

vendor/wheels/Global.cfc

@@ -4389,6 +4389,24 @@ return local.$wheels;
 		return protectedMethods;
 	}
 
+	/**
+	 * Convert the comma-list returned by `$buildProtectedControllerMethods()`
+	 * into a struct-as-set so `$callAction()` can perform an O(1)
+	 * `StructKeyExists` membership test on the per-request dispatch hot path
+	 * instead of an O(n) `ListFindNoCase` scan over ~100-250 helper names.
+	 * CFML struct keys are case-insensitive by default, preserving the prior
+	 * `ListFindNoCase` semantics (an action named `ENV` is still rejected like
+	 * `env`). Stored on `application.wheels.protectedControllerMethodsLookup`
+	 * alongside the list, which is retained for callers expecting that shape.
+	 */
+	public struct function $protectedControllerMethodsLookup(required string methods) {
+		var lookup = {};
+		for (var name in ListToArray(arguments.methods)) {
+			lookup[name] = true;
+		}
+		return lookup;
+	}
+
 	/**
 	 * Re-evaluate the given global-includes file into `application.wo`'s
 	 * variables/this scope. Invoked from the bare `?reload=true` soft-reload

vendor/wheels/controller/processing.cfc

@@ -135,7 +135,7 @@ component {
 	 * Internal function.
 	 */
 	public void function $callAction(required string action) {
-		if (Left(arguments.action, 1) == "$" || ListFindNoCase(application.wheels.protectedControllerMethods, arguments.action)) {
+		if (Left(arguments.action, 1) == "$" || StructKeyExists(application.wheels.protectedControllerMethodsLookup, arguments.action)) {
 			// A helper-named or $-prefixed action is treated exactly like a
 			// missing action: it 404s (see #2845 and CLAUDE.md Anti-Pattern 8).
 			// Route through $throwErrorOrShow404Page — mirroring RecordNotFound /

vendor/wheels/databaseAdapters/Base.cfc

@@ -417,6 +417,32 @@ component output=false extends="wheels.Global"{
 		local.args.username = variables.username;
 		local.args.password = variables.password;
 		local.args.table = arguments.tableName;
+
+		// Column metadata is a JDBC catalog round-trip (cfdbinfo type="columns")
+		// fetched once per model class. On remote / wide-schema databases that
+		// round-trip dominates first-request latency, and it is otherwise re-paid
+		// on every reload and for every model sharing a table. When
+		// cacheDatabaseSchema is on, memoize the result per datasource+table in
+		// application.wheels.schemaColumnCache. A reload rebuilds the application
+		// scope, so schema changes are still picked up on reload — the same
+		// contract as the model and controller config caches. The cache lives
+		// OUTSIDE application.wheels.cache.* on purpose: those categories hold
+		// {value, expiresAt} envelopes walked by the time-based cull, which would
+		// throw on a raw query. The read mirrors $getFromCache (try/catch +
+		// Duplicate) so a concurrent struct read can't surface a partial value and
+		// a caller can't mutate the cached query in place. (perf)
+		local.cacheSchema = $get("cacheDatabaseSchema");
+		if (local.cacheSchema) {
+			local.cacheKey = Hash(variables.dataSource & Chr(31) & arguments.tableName);
+			try {
+				if (StructKeyExists(application.wheels.schemaColumnCache, local.cacheKey)) {
+					return Duplicate(application.wheels.schemaColumnCache[local.cacheKey]);
+				}
+			} catch (any e) {
+				// fall through to a fresh catalog lookup on any concurrent-read hiccup
+			}
+		}
+
 		if ($get("showErrorInformation")) {
 			try {
 				local.rv = $getColumnInfo(argumentCollection = local.args);
@@ -430,6 +456,14 @@ component output=false extends="wheels.Global"{
 		} else {
 			local.rv = $getColumnInfo(argumentCollection = local.args);
 		}
+
+		if (local.cacheSchema) {
+			// Store an isolated copy so the cached entry can never be mutated via a
+			// reference handed to an earlier caller.
+			lock name="wheels.schemaColumnCache" type="exclusive" timeout="10" {
+				application.wheels.schemaColumnCache[local.cacheKey] = Duplicate(local.rv);
+			}
+		}
 		return local.rv;
 	}
 

vendor/wheels/events/onapplicationstart.cfc

@@ -109,6 +109,13 @@ component {
 		}
 		application.$wheels.controllers = {};
 		application.$wheels.models = {};
+		// Per-app column-metadata cache (see databaseAdapters/Base.cfc $getColumns).
+		// Deliberately a SIBLING of `cache`, not a `cache.*` category: it stores raw
+		// query objects that live for the application lifetime, whereas every
+		// `cache.*` category holds {value, expiresAt} envelopes that the cull/count
+		// machinery ($addToCache / $cacheCount) walks and dereferences `.expiresAt`
+		// on. Putting schema queries under `cache.*` makes the cull throw.
+		application.$wheels.schemaColumnCache = {};
 		application.$wheels.helperFileCache = {};
 		application.$wheels.layoutFileCache = {};
 		application.$wheels.existingObjectFiles = {};
@@ -400,6 +407,13 @@ component {
 		// helpers like env(), model(), redirectTo() are never URL-invokable.
 		application.$wheels.protectedControllerMethods = application.wo.$buildProtectedControllerMethods();
 
+		// Companion struct-as-set for O(1) membership checks on the dispatch hot
+		// path (see $callAction()); the comma-list above is kept for callers that
+		// expect that shape.
+		application.$wheels.protectedControllerMethodsLookup = application.wo.$protectedControllerMethodsLookup(
+			application.$wheels.protectedControllerMethods
+		);
+
 		// Enable the main GUI Component
 		if (application.$wheels.enablePublicComponent) {
 			application.$wheels.public = application.wo.$createObjectFromRoot(path = "wheels", fileName = "Public", method = "$init");