Subpath-relative Thumbor URLs (`PGTHUMBOR_SERVER_URL=/thumbor`) break image_scales metadata rendering

[jensens]

Context

We run Thumbor behind the same origin as Plone, under a subpath (/thumbor/), and we have multiple Plone subsites on different hostnames. In this setup, PGTHUMBOR_SERVER_URL should be a path only — e.g. /thumbor — so the browser resolves each image URL against the current subsite's host, not a fixed Thumbor hostname baked in at index time.

Direct access via @@images/<uid> (no brain metadata involved) already works with PGTHUMBOR_SERVER_URL=/thumbor, because ThumborImageScale._scale_url returns "/thumbor/<hmac>/.../<zoid>/<tid>" and the browser resolves that against the current host.

The breakage is on the brain image_scales metadata path (listings, summary views, search results — anything that reads pre-rendered scale URLs out of the catalog column instead of loading the object).

Analysis (plone.namedfile 8)

The write path goes:

1. Products.CMFPlone.image_scales.indexer.image_scales(obj) → IImageScalesAdapter.

2. Products.CMFPlone.image_scales.adapters.ImageScales iterates the Dexterity schemata and asks IImageScalesFieldAdapter per image field.

3. plone.namedfile.adapters.ImageFieldScales calls @@images (→ our ThumborImageScaling), then stores the URL via:

   # plone/namedfile/adapters.py (8.0.0a4, unchanged from 7.x)
   def _scale_view_from_url(self, url):
       # "common case is a local path to @@images/foo-scale"
       return url.replace(self.context.absolute_url(), "").lstrip("/")

   With PGTHUMBOR_SERVER_URL=/thumbor, url is "/thumbor/<hmac>/.../<zoid>/<tid>". context.absolute_url() is https://…/folder/doc, so .replace(...) is a no-op. Then .lstrip("/") eats the leading slash, and the catalog metadata ends up storing:

   "thumbor/<hmac>/.../<zoid>/<tid>"
   

The read path is NavigationRootScaling._tag_from_brain_image_scales:

# plone/namedfile/scaling.py (8.0.0a4)
src = (
    data["download"]
    if data["download"].startswith("http")
    else f"{brain.getURL()}/{data['download']}"
)

Since the stored value no longer starts with http (and no longer starts with / either), it hits the else branch and the final src becomes:

https://site-a.example/folder/doc/thumbor/<hmac>/.../<zoid>/<tid>

The Thumbor subpath is concatenated after the document path instead of living at the host root. The browser then requests a non-existent URL → 404 / broken image, but only when rendering happens from the brain metadata — direct object rendering still works, which makes this easy to miss in isolated tests.

With an absolute PGTHUMBOR_SERVER_URL (https://thumbor.example) — for comparison

_scale_view_from_url's .replace() and .lstrip("/") are both no-ops (no overlap with context.absolute_url(), no leading slash), so the full absolute Thumbor URL lands in the metadata verbatim. The read path then hits the startswith("http") branch and passes it through unchanged. This is the only case that currently works for brain-metadata rendering, and it hard-codes the Thumbor hostname into every catalog row — which is what breaks multi-host / subsite deployments.

Impact

• Subpath deployments (/thumbor) are broken on any template that renders from image_scales brain metadata (standard listings, summary / tile views, REST API serializations, anything going through NavigationRootScaling.tag(brain, ...)).
• Absolute deployments work, but bake the Thumbor hostname into the catalog. Host rename, key rotation, or moving Thumbor to a different domain require a full @@thumbor-purge-scales reindex.
• Multi-host / subsite deployments can't express "relative to whichever host served the page" at all today.

Proposed fix (discussion)

Two small, targeted overrides in plone.pgthumbor, both bound to IPlonePgthumborLayer. No new config flag — PGTHUMBOR_SERVER_URL=/thumbor becomes the single knob.

1. Write side — custom IImageScalesFieldAdapter

Register a subclass of plone.namedfile.adapters.ImageFieldScales for (INamedImageField, IDexterityContent, IPlonePgthumborLayer) that overrides _scale_view_from_url to preserve absolute-origin and root-relative URLs verbatim:

def _scale_view_from_url(self, url):
    if url.startswith(("http://", "https://", "/")):
        return url  # Thumbor URL — leave intact
    return super()._scale_view_from_url(url)

Result: the catalog stores "/thumbor/<hmac>/.../<zoid>/<tid>" verbatim (leading slash preserved), or the full https://thumbor.example/... form when configured that way.

2. Read side — ThumborNavigationRootScaling

Subclass NavigationRootScaling and register it as the @@image_scale view on INavigationRoot in our layer. Override _tag_from_brain_image_scales so the pass-through branch also accepts root-relative paths:

download = data["download"]
if download.startswith(("http://", "https://", "/")):
    src = download
else:
    src = f"{brain.getURL()}/{download}"

Browser resolution then does the right thing automatically:

• Absolute URL (https://thumbor.example/...) → used as-is.
• Root-relative URL (/thumbor/...) → resolved against the current request host, so subsite-A gets https://site-a.example/thumbor/... and subsite-B gets https://site-b.example/thumbor/..., from the same catalog row.
• Legacy relative path (@@images/...) → resolved against brain.getURL(), unchanged behavior.

Trade-off

Toggling between absolute-host and subpath forms on an existing site requires a @@thumbor-purge-scales reindex, because the stored form is different. This is consistent with how security_key rotation, Thumbor host changes, and paranoid-mode toggles already work today — no new class of "requires reindex after config change" is introduced.

Out of scope

• No change to url.py or config.py.
• No new environment variable.
• No change to the direct-access @@images/<uid> path (already works).
• plone.namedfile < 8 support — we've standardized on 8.

Test plan

• Unit tests for the new _scale_view_from_url override (absolute, root-relative, legacy relative).
• Unit tests for _tag_from_brain_image_scales override (all three forms).
• Functional test that simulates an indexed brain with a /thumbor/... download and verifies the rendered <img src="..."> is the root-relative path (so the browser resolves it against the current host).

[jensens]

Update: additional scenarios + revised approach

The original analysis above covered three of the hosting scenarios we actually need to support, but missed two important ones. Expanding the scenario matrix:

#	Deployment	Example URLs	Single-value PGTHUMBOR_SERVER_URL that works today	Covered by original proposal?
1	Thumbor on its own domain / CDN	https://cdn.example/thumbor/ + https://plone.example/…	https://cdn.example/thumbor	✅ (today)
2	Thumbor as subpath on the same host, single Plone site	https://plone.example/thumbor/ + https://plone.example/…	/thumbor	✅ (original proposal)
3	Multiple subsites on different hostnames, shared Thumbor subpath	https://site-a.example/thumbor/…, https://site-b.example/thumbor/…	/thumbor	✅ (original proposal — browser resolves against current host)
4	Plone under a subpath, Thumbor at host root	https://arch.example/2019/… + https://arch.example/thumbor/…	/thumbor	⚠️ works by accident — only because Thumbor happens to sit a level above the Plone mount
5	Plone under a subpath, Thumbor under the same subpath	https://arch.example/2019/… + https://arch.example/2019/thumbor/…	none	❌ no single value of PGTHUMBOR_SERVER_URL produces the right URL
6	Several parallel Plone subpath mounts in one Zope (/2017, /2019, /2021, each with its own <mount>/thumbor/)	https://arch.example/2019/thumbor/… and https://arch.example/2017/thumbor/… from the same running instance	none	❌ a single config value fundamentally cannot express this — the correct prefix is only known at render time, based on the active navigation root
7	Plone under a subpath, Thumbor on a different host	https://arch.example/2019/… + https://thumbor.arch.example/	https://thumbor.arch.example	✅ (absolute form)
8	Multi-navigation-root inside one Plone site	https://plone.example/sites/a/…, https://plone.example/sites/b/… + shared Thumbor	/thumbor	✅ (original proposal)

Scenarios 5 and 6 are the real gap. Scenario 6 is the strongest case: with a single Zope serving several yearly archives, each with its own Thumbor mount at <archive>/thumbor/, the correct URL prefix is only knowable at render time from the active navigation root — no single config value can produce it.

Other things to account for

• VHM awareness. context.absolute_url() already reflects the externally-visible path including any subpath. For the read side, NavigationRootScaling.context is the navigation root, so self.context.absolute_url() gives us exactly the scenario-6 prefix (https://arch.example/2019) at render time — no extra lookup.
• Write side direct access (@@images/<uid>). ThumborImageScale.context is the content object, not the navigation root. When resolving for direct access we call plone.api.portal.get_navigation_root(self.context).absolute_url() — cheap, once per scale view creation.
• Host rename / mount relocation. With render-time resolution, neither a host rename nor moving Thumbor to a different subpath requires a reindex. The HMAC-signed path portion stays unchanged; only the prefix is recomputed.
• Security-key rotation. Still requires a reindex (the HMAC is baked into the signed path). This is unchanged.
• Caching (Varnish / CDN). The rendered src is stable per page (not per user), so anonymous cache works. For scenario 6 each subsite's cache entries get their own prefix naturally, because the rendered HTML carries the right one.

Revised fix proposal

Core idea: decouple storage from host/prefix. The image_scales metadata stores only the signed path portion (what libthumbor.CryptoURL.generate() produces — <hmac>/300x200/fit-in/smart/<zoid>/<tid>) plus a "thumbor": True marker. The prefix is computed at render time from PGTHUMBOR_SERVER_URL + the current navigation root, depending on the form of the config value.

Three accepted forms of PGTHUMBOR_SERVER_URL, distinguished purely syntactically — no new config flag:

Config form	Example	Rendering	Target scenario
Absolute URL (http:// / https://)	https://cdn.example/thumbor	{server_url}/{signed_path}	#1, #7 — dedicated host / CDN
Root-relative path (leading /)	/thumbor	{server_url}/{signed_path} — browser resolves against current host	#2, #3, #8 — shared subpath, multi-host
Nav-root-relative path (no scheme, no leading /) — new	thumbor	{navigation_root.absolute_url()}/{server_url}/{signed_path}	#5, #6 — Plone under subpath, Thumbor under the same mount

One knob covers all the scenarios that can actually work. Scenario 4 keeps working through form "root-relative path".

Storage shape:

{
  "download": "<signed_path>",
  "thumbor": true,
  "width": 300,
  "height": 200
}

The "thumbor": true marker lets the read path distinguish Thumbor-generated entries from any legacy @@images/<uid> entries that may still coexist in the same catalog (e.g. non-image fields, or fields on content types where Thumbor is skipped). Legacy entries continue to render via the standard brain.getURL() concatenation — full backwards-compatibility inside a mixed site.

Read side (ThumborNavigationRootScaling._tag_from_brain_image_scales):

download = data["download"]
if data.get("thumbor"):
    cfg = get_thumbor_config()
    prefix = _resolve_prefix(cfg.server_url, self.context)  # self.context is the nav-root
    src = f"{prefix}/{download}"
else:
    src = data["download"] if download.startswith(("http://", "https://", "/")) \
          else f"{brain.getURL()}/{download}"

Write side (custom IImageScalesFieldAdapter): store only the signed path + marker. No more _scale_view_from_url path-munging for Thumbor entries.

Trade-offs

• Introduces a new storage shape → one-time @@thumbor-purge-scales migration when upgrading from current absolute-URL storage. After that, switching between config forms requires no reindex. This is a strict improvement over the current "any URL-form change needs a reindex" state.
• Slightly more work at render time (prefix resolution), but it's pure string construction against an already-materialized absolute_url() — negligible compared to the rest of a brain render.
• The "thumbor": true marker is additive; deserializers that don't know about it simply ignore it.

Out of scope (unchanged)

• url.py and config.py stay put (config parser only gains form validation).
• No new environment variable.
• plone.namedfile < 8 support — standardized on 8.
• Direct-access @@images/<uid> — same flow as today, using the same _resolve_prefix helper.

[jensens]

Two notes from #15, which is now closed and points here for the part that remains.

#15's rendering half is this issue. Same mechanism — _scale_view_from_url eats the leading slash off a host-root path, startswith("http") then fails, and the renderer emits {image_url}/thumbor/<signed>. It was filed from one deployment's symptoms and does not know about scenarios 5 and 6 from the comment above, so this is the better place to answer it.

The surface here is smaller than it was. ImageFieldScales has two outputs that were both wrong, and one of them is now fixed separately.

The top-level download — the "original" — no longer goes through Thumbor at all. plone.pgthumbor.adapters.ThumborImageFieldScales overrides get_original_image_url to return @@images/{fieldname}, which Plone serves from the original blob. That was not a URL-shape problem: asking an image processor for a 1:1 render is the wrong request however the URL is spelled, and since source derivatives landed it had stopped being a render of the original at all. PR #37, in 0.7.1 (unreleased).

So the adapter this issue proposes does not need to deal with get_original_image_url. It only has to get the per-scale download values right, which is the part the scenario matrix actually constrains. A test in tests/test_adapters.py pins that get_scales is still the inherited one and that get_original_image_url is the only method overridden, so extending the same class here will not silently collide.

One thing worth deciding early when picking this up: the revised proposal stores the signed path plus a marker and computes the prefix at render time. That changes what sits in the image_scales column, so existing rows need rewriting — which means a migration step, and purge_scales is now chunked and resumable (#16, also in 0.7.1) if that turns out to be the vehicle.