Skip to content

Commit

Permalink
Allow manifest processing to be invoked without going through an HTML…
Browse files Browse the repository at this point in the history 
… document (#1069)

* Processing the manifest: Simplify the interface.

Replaces the link and response parameters with document URL and manifest URL.

These parameters were only used to get the document URL and manifest
URL, respectively, so it doesn't make sense to accept the much bulkier
HTML objects. This was limiting the ability to call the processing
algorithm from outside an HTML document context, which is a future
direction we wish to explore.

Note that the only call to this algorithm is in the HTML spec, which
needs to be updated simultaneously to use the new interface.

Pre-work for #668.

* Added new normative text (with a non-normative note) allowing user
agents to invoke the processing steps without a document, provided that
they supply a valid document URL.

* Reword non-normative note.

* Correctly link.

(Actually this makes the wrong link, but it's a respec bug: https://github.com/w3c/respec/issues/4435

* Added a SHOULD to set CORS correctly.

Note: There's a reference error here because HTML doesn't export a term. I'm getting it exported.

* Move all this text to its own section; it's getting a bit much.

* Use variables to avoid repeating complex sentences.

* Rewrote processing without a document section for clarity and correctness.

- Changed MUST into a SHOULD. We can't really expect all uses to
  directly verify this.
- Removed the "or" clause that the document be same-origin as manifest;
  you still want a link from the document to the manifest either way.
- Added "at least at some point in the past", to acknowledge that you
  don't need to verify this at install time, just whenever you did the
  caching.
- Clarify that the CORS request is only needed if the manifest is not
  same-origin as the document.

* Apply suggestions from code review

Co-authored-by: Marcos Cáceres <[email protected]>

* Respond to review.

---------

Co-authored-by: Marcos Cáceres <[email protected]>
  • Loading branch information
@mgiuca @marcoscaceres
mgiuca and marcoscaceres authored May 2, 2023
1 parent 0252939 commit 22a0b1e
Showing 1 changed file with 56 additions and 9 deletions.
65 changes: 56 additions & 9 deletions index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1254,15 +1254,10 @@ <h3>
<p>
The steps for <dfn data-export="" data-local-lt=
"processing">processing a manifest</dfn> are given by the following
algorithm. The algorithm takes [^link^] |el:HTMLLinkElement|, a
[=Response=] |response|, and a [=byte sequence=] |bodyBytes|.
algorithm. The algorithm takes a [=URL=] |document URL:URL|, a
[=URL=] |manifest URL:URL|, and a [=byte sequence=] |bodyBytes|.
</p>
<ol class="algorithm">
<li>Let |document URL:URL| be |el|'s [=Node/node document=]'s
[=Document/URL=].
</li>
<li>Assert: |document URL:URL| is not null.
</li>
<li>Let |json| be the result of [=parse JSON bytes to an Infra
value=] passing |bodyBytes|.
</li>
Expand All @@ -1285,8 +1280,6 @@ <h3>
<li>[=Process a text member=] passing |json|, |manifest|, and
"short_name".
</li>
<li>Let |manifest URL:URL| be |response|'s [=response/URL=].
</li>
<li>[=Process the `start_url` member=] passing |json|, |manifest|,
|manifest URL|, and |document URL|.
</li>
Expand Down Expand Up @@ -1382,6 +1375,60 @@ <h2>
</li>
</ol>
</section>
<section>
<h3>
Processing the manifest without a document
</h3>
<p>
The [=processing a manifest=] steps are invoked by [[HTML]]'s
processing steps for the [^link^] element, but MAY also be invoked
by the user agent to process a manifest without an associated
[=document=].
</p>
<p>
In this case, to match the guarantees made by the corresponding
steps in [[HTML]], the user agent SHOULD ensure that at least at
some point in the past:
</p>
<ul>
<li>there was at least one [=document=] that is [=same origin=] as
|document URL:URL| that has a [^link^] element
|linkElement:HTMLLinkElement| with a [^link/rel^] of
[^link/rel/manifest^] and a [^link/href^] that resolves to
|manifest URL:URL|, and that
</li>
<li>if |manifest URL| is not [=same origin=] as |document URL|, the
|bodyBytes:byte sequence| data was [=fetch|fetched=] with a [=CORS
Request=] whose <a data-xref-type="http-header">`Origin`</a> is
|document URL|'s [=url/origin=], and whose [=Request/credentials
mode=] is set to the [=CORS settings attribute credentials mode=]
for |linkElement|'s [^link/crossorigin^] attribute.
</li>
</ul>
<aside class="note" title="The rationale for these checks">
<p>
This provision allows user agents to perform app installations
using a manifest without having to first load a document that
links to the manifest (e.g. when installing an app onto the
user's device via a sync service). But the above recommendations
ask the user agent to verify that, when an application scope is
on origin A and the manifest is on a different origin B, there is
a bidirectional relationship between the two origins.
</p>
<p>
The first check ensures that at least some page on origin A links
to the manifest on origin B (otherwise, it would be possible for
a manifest on origin B to control the metadata for an
unaffiliated app on origin A).
</p>
<p>
The second check ensures that origin B allows (via the [=CORS
protocol=]) its manifest to be applied by origin A, and also that
the manifest is fetched with or without credentials, as agreed by
both origins, as it would if going directly through the document.
</p>
</aside>
</section>
<section>
<h3 id="applying">
Applying the manifest
Expand Down

0 comments on commit 22a0b1e

Please sign in to comment.