feat: add hlx6 support for api.aem.live content routing by kptdobe · Pull Request #242 · adobe/da-universal

kptdobe · 2026-06-30T14:44:40Z

Description

This change routes source GET, HEAD, and POST requests to api.aem.live for source-bus sites.
Legacy sites continue through the da-admin service binding.

Each source operation sends an unauthenticated GET to admin.hlx.page/ping/{org}/{site}.
The x-api-upgrade-available: true header selects the source bus.
The worker does not cache the result.
helix-admin#3687 sets this header for source-bus sites.
It checks whether content.source.url starts with https://api.aem.live/.
helix-admin#3689 added the /ping route.

If the probe fails, reads use da-admin.
If the probe fails before a write, the worker sends parallel HEAD requests to both backends.
The backend that answers 200 wins.
Two 404 responses select da-admin for a new page.
Two 200 responses select api.aem.live and log a warning.
A rejected HEAD request selects da-admin.

Legacy sites are the majority and do not need admin.hlx.page.
Failing them closed on a ping error would cause the larger outage.

Source responses with 401, 403, or 5xx pass through unchanged.
Only 404 uses the new-page template.

Related Issue

Unblocks adobe/da-live#1066.
Uses helix-admin#3687 and helix-admin#3689.

Motivation and Context

Helix 6 stores media in the source bus until preview.
The preview proxy had no source-bus read path, so source-bus media returned 404.
DA Live uses the preview domain to keep IMS credentials out of page scripts.

Known limits

Each source request adds a /ping round trip.
Measured from Frankfurt: 0.483s, 0.498s, 0.519s.
The response has cache-control: no-store, private, must-revalidate, so CDN caching does not help.
The endpoint advertises x-ratelimit-limit: 10.
Source-bus sites still load site config from da-admin through getSiteConfig.
An unlikely DA to hlx6 source change between a GET and its POST is not handled in this PR. Closing that race needs coordinated conditional-write support across da-live, da-admin, and this worker.

How Has This Been Tested?

Unit: 236 tests pass, and npm run lint reports no errors.
Before on main: the preview image request returned 404 with 398 bytes.
After on hlx6-ping: local preview returned 200 with 3,669,975 bytes.
The local payload matched the direct source response by SHA-256.
admin.hlx.page/ping/benpeter/hlx6-test returned 200 with x-api-upgrade-available: true.
Authenticated source GET for benpeter/hlx6-test/index.html returned 200 with 150 bytes.

Screenshots

Not applicable.

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature which changes existing functionality)

Checklist

I have signed the Adobe Open Source CLA.
My code follows the code style of this project.
My change requires a documentation change.
I have updated the documentation accordingly.
I have read the CONTRIBUTING document.
I have added tests to cover my changes.
All new and existing tests passed.

tripodsan

wrong test

tripodsan · 2026-06-30T15:40:23Z

+  const cached = hlx6Cache.get(key);
+  if (cached !== undefined) return cached;
+
+  const resp = await fetch(aemApiSourceUrl(org, site, '/'), {


no, this is the wrong "ping". every helix5 project is automatically a helix6 project....

you need to request: https://admin.hlx.page/ping/{org}/{site} and then check if the

x-api-upgrade-available header is true

and even then, it is not guaranteed that the respective site has the source bus configured.
we probably need a better way to detect this.

@bosschaert what about returning 405 for /{org}/sites/{site}/source/ if the content source is not correct?

The HTTP 405 Method Not Allowed client error response status code indicates that the server knows the request method, but the target resource doesn't support this method.

if we would implement this, you're check would also need to allow 404

tripodsan

wrong check

tripodsan · 2026-06-30T15:49:04Z

+  const cached = hlx6Cache.get(key);
+  if (cached !== undefined) return cached;
+
+  const resp = await fetch(aemApiSourceUrl(org, site, '/'), {


and even then, it is not guaranteed that the respective site has the source bus configured.
we probably need a better way to detect this.

@bosschaert what about returning 405 for /{org}/sites/{site}/source/ if the content source is not correct?

The HTTP 405 Method Not Allowed client error response status code indicates that the server knows the request method, but the target resource doesn't support this method.

if we would implement this, you're check would also need to allow 404

andreituicu · 2026-07-02T15:28:40Z

we probably need a better way to detect this.

Would it not be easier to send out two fetches in parallel?

hlx6 API: api.aem.live/${org}/sites/${site}/source/cat.jpg or document.html
DA Admin API: admin.da.live/source/${org}/${site}/cat.jpg or document.html

waiting on their response and then doing a fallback.
If 1. hlx 6 API is 200 -> it is a hlx6 project -> return the content
else fallback to the DA Admin response (200, or 404, it doesn't matter, if it is not there, it is nowhere else)

That way we don't need a special detection mechanism. Would work even for projects that may end up with mixed content between DA Admin and HLX6 (for whatever edge case).

benpeter · 2026-07-28T09:02:43Z

Would it not be easier to send out two fetches in parallel?

@andreituicu, with helix-admin#3687 and #3689, /ping now returns 200 for every site, and helix-admin adds x-api-upgrade-available for source-bus sites. I think using that signal is safer than requesting every resource from both backends.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

benpeter · 2026-07-28T09:40:59Z

rebased on main and adjusted to changes in #240

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

andreituicu · 2026-07-28T12:00:14Z

sure, not at all against the probing solution. it is the faster and less wasteful solution with cache, so clearly more optiomal.

in terms of safest, in my mind the getting from both places was the safest option, because the content is either there in one of the two places or its a 404. there is no possibility of the probe being wrong, the content being mixed between Helix and DA, site being in migration, or any of the multiple edge cases, or in-between states that might be encountered during the Helix 6 transition.

that's just to explain why I proposed it, but still, nothing against if go the probe route.
at this time, nothing works, so having a solution in place is clearly the most important thing and issues, bugs, edge cases can be fixed from there forward.

benpeter · 2026-07-28T12:32:27Z

@andreituicu Agreed on simplicity. my concern was rollback: if a site moves back to DA but the migrated copy is still in source bus, an H6-first read would keep returning it even if content.source.url no longer points to api.aem.live. same for deletions: a stale copy could turn a 404 into a 200.

I have also removed the routing cache locally. probably YAGNI, and it is per CF isolate anyway, so different isolates could route the same site differently during cutover.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

tripodsan

several issues.

tripodsan · 2026-07-29T12:02:22Z

+    const daPath = `${path}.${ext}`;
+    let hlx6 = await probeHlx6(org, site);
+    if (hlx6 === undefined) {
+      hlx6 = await resolveUncertainWriteBackend({


I don't understand this check. if it's not hlx6, then it's not hlx6...

undefined means that the probe failed, in which case resolveUncertainWriteBackend will HEAD both backends and use api.aem.live if the document exists there, otherwise da-admin. I'll add JSDoc to explain, yes.

but if the probe fails, why should the HEAD request then be a good alternative?

and for a new file, resolveUncertainWriteBackend it will also return false, because its a 404.

Co-authored-by: Tobias Bocanegra <tripod@bocanegra.ch>

tripodsan · 2026-07-29T13:50:29Z

-  );
+  let sourceResp;
+  if (hlx6) {
+    const sourceUrl = aemApiSourceUrl(org, site, `${path}.${ext}`);


but path already has the ext, no?

tripodsan

the entire daCtx path / ext / html / ... handling is uninuitive and not documented.
I would first (in a different PR) harmonize this.

benpeter · 2026-07-31T15:56:08Z

the entire daCtx path / ext / html / ... handling is uninuitive and not documented. I would first (in a different PR) harmonize this.

sketched the harmonization in #256

benpeter · 2026-08-01T21:31:05Z

the entire daCtx path / ext / html / ... handling is uninuitive and not documented. I would first (in a different PR) harmonize this.

PR is #261

kptdobe requested review from andreituicu, bosschaert and mhaack June 30, 2026 14:45

kptdobe mentioned this pull request Jun 30, 2026

fix(hlx6): load hlx6 media images via authenticated source API adobe/da-live#1066

Open

3 tasks

tripodsan requested changes Jun 30, 2026

View reviewed changes

benpeter and others added 3 commits July 28, 2026 11:10

test: cover Helix 6 source routing

f057144

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

test: cover ping timeout recovery

bf254ed

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

feat: route source-bus traffic through Helix 6

1eb95c9

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

benpeter force-pushed the feat/hlx6-support branch from e285b78 to 1eb95c9 Compare July 28, 2026 09:40

benpeter marked this pull request as draft July 28, 2026 09:45

benpeter and others added 3 commits July 28, 2026 13:50

test: require fresh source routing probes

d67853a

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

refactor: remove source routing cache (KISS)

3449993

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

test: clean routing transition setup

f266c20

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

benpeter and others added 10 commits July 28, 2026 14:38

test: cover workerd probe failures

309cc2d

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

fix: handle all source probe failures

e5d5146

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

test: align unknown source writes

91c565e

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

fix: align unknown source routing

237e555

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

test: preserve source read failures

df3c112

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

fix: preserve source read failures

e52569b

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

test: route uncertain writes by backend evidence

65c2cd0

fix: resolve uncertain writes by backend evidence

7b65a91

test: preserve fulfilled source HEAD evidence

cbba3ba

fix: keep fulfilled HEAD evidence

29a7757

benpeter marked this pull request as ready for review July 28, 2026 14:44

benpeter requested a review from tripodsan July 28, 2026 14:44

benpeter added 5 commits July 29, 2026 10:47

test: reject source routing warnings

3d12ed8

fix: remove source routing warnings

0222c9f

test: reject source bus request logs

a70838a

fix: remove source bus request logs

ecf9410

Merge remote-tracking branch 'origin/main' into hlx6-ping

6f5fc11

tripodsan reviewed Jul 29, 2026

View reviewed changes

Comment thread src/routes/da-admin.js

tripodsan reviewed Jul 29, 2026

View reviewed changes

Comment thread src/routes/da-admin.js Outdated

tripodsan reviewed Jul 29, 2026

View reviewed changes

Comment thread src/routes/da-admin.js

tripodsan reviewed Jul 29, 2026

View reviewed changes

Comment thread src/routes/da-admin.js

tripodsan requested changes Jul 29, 2026

View reviewed changes

benpeter and others added 6 commits July 29, 2026 14:42

fix(dry): don't repeat default method

74b1399

Co-authored-by: Tobias Bocanegra <tripod@bocanegra.ch>

refactor: simplify da-admin source fetch

0cc671e

Co-authored-by: Tobias Bocanegra <tripod@bocanegra.ch>

refactor: return source HEAD response directly

12e6198

Co-authored-by: Tobias Bocanegra <tripod@bocanegra.ch>

refactor: don't repeat default method

42d21ba

Co-authored-by: Tobias Bocanegra <tripod@bocanegra.ch>

test: require source bus request logs

a6b7579

fix: align source bus request logging

d769ad6

benpeter requested a review from tripodsan July 29, 2026 13:28

benpeter added 2 commits July 29, 2026 15:37

test: preserve explicit source extensions

339fb37

fix: preserve explicit source extensions

d25d4c1

tripodsan reviewed Jul 29, 2026

View reviewed changes

tripodsan requested changes Jul 29, 2026

View reviewed changes

benpeter marked this pull request as draft July 29, 2026 14:11

benpeter mentioned this pull request Jul 31, 2026

Source URLs are built from daCtx.path, so / resolves to /.html #256

Closed

benpeter mentioned this pull request Aug 3, 2026

feat: route to the site's content store #263

Merged

benpeter mentioned this pull request Aug 12, 2026

fix: ask the config service whether a site exists, not head.html #270

Merged

Uh oh!

Conversation

kptdobe commented Jun 30, 2026 • edited by benpeter Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Related Issue

Motivation and Context

Known limits

How Has This Been Tested?

Screenshots

Types of changes

Checklist

Uh oh!

tripodsan left a comment

Choose a reason for hiding this comment

Uh oh!

tripodsan Jun 30, 2026

Choose a reason for hiding this comment

Uh oh!

tripodsan Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tripodsan left a comment

Choose a reason for hiding this comment

Uh oh!

tripodsan Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

andreituicu commented Jul 2, 2026

Uh oh!

benpeter commented Jul 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

benpeter commented Jul 28, 2026

Uh oh!

andreituicu commented Jul 28, 2026

Uh oh!

benpeter commented Jul 28, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tripodsan left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tripodsan Jul 29, 2026

Choose a reason for hiding this comment

Uh oh!

benpeter Jul 29, 2026

Choose a reason for hiding this comment

Uh oh!

tripodsan Jul 29, 2026

Choose a reason for hiding this comment

Uh oh!

tripodsan Jul 29, 2026

Choose a reason for hiding this comment

Uh oh!

tripodsan left a comment

Choose a reason for hiding this comment

Uh oh!

benpeter commented Jul 31, 2026

Uh oh!

benpeter commented Aug 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

kptdobe commented Jun 30, 2026 •

edited by benpeter

Loading

tripodsan Jun 30, 2026 •

edited

Loading

tripodsan Jun 30, 2026 •

edited

Loading

benpeter commented Jul 28, 2026 •

edited

Loading