Adding file_handlers and launch consumer #1005
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
|
|
@@ -1012,6 +1012,158 @@ <h3> | |||||
| conventions or limitations of the host operating system. | ||||||
| </p> | ||||||
| </section> | ||||||
| <section> | ||||||
| <h3> | ||||||
| `file_handlers` member | ||||||
| </h3> | ||||||
| <p> | ||||||
| The [=manifest's=] <code><dfn data-export="" data-dfn-for= | ||||||
| "manifest">`file_handlers`</dfn></code> member is a [=list=] that | ||||||
| represents URLs within the app that handles launches of given [=file | ||||||
dmurph marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| types=]. | ||||||
| </p> | ||||||
| <p> | ||||||
| A <dfn>file type</dfn> refers to file that has a [=mime type=] and/or | ||||||
dmurph marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| ends with a [=file extension=]. A <dfn>file extension</dfn> is a | ||||||
| string that start with a "." and only contains [=valid suffix code | ||||||
| points=]. A <dfn>valid suffix code point</dfn> is a [=code point=] | ||||||
| that is [=ASCII alphanumeric=], U+002B (+), or U+002E (.). | ||||||
| Additionally, [=file extensions=] are are limited to a length of 16 | ||||||
| code points. | ||||||
| </p> | ||||||
| <aside class="note"> | ||||||
| <p> | ||||||
| Note: These code points were chosen to support most pre-existing | ||||||
| file formats. The vast majority of file extensions are purely | ||||||
| alphanumeric, but compound extensions (such as .tar.gz) and | ||||||
| extensions such as .c++ for C++ source code are also fairly common, | ||||||
| hence the inclusion of + and . as allowed code points. | ||||||
| </p> | ||||||
| </aside> | ||||||
| <p> | ||||||
| How file handlers are registered and disambiguated is at the | ||||||
| discretion of the operating system. | ||||||
dmurph marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| </p> | ||||||
| <p> | ||||||
| To <dfn>process the `file_handlers` member</dfn>, given [=ordered | ||||||
| map=] |json:ordered map|, and [=ordered map=] |manifest:ordered map|: | ||||||
| </p> | ||||||
| <ol class="algorithm"> | ||||||
| <li>Let |processedFileHandlers:list| be a new [=list=]. | ||||||
| </li> | ||||||
| <li>Set |manifest|["file_handlers"] to |processedFileHandlers|. | ||||||
| </li> | ||||||
marcoscaceres marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| <li>If |json|["file_handlers"] doesn't [=map/exist=] or | ||||||
| |json|["file_handlers"] is not a [=list=], return. | ||||||
| </li> | ||||||
| <li>[=list/For each=] |entry:ordered map| of |json|["file_handlers"]: | ||||||
| <ol> | ||||||
| <li>Let |file_handler:ordered map| be [=process a file handler | ||||||
| item=] with |entry|. | ||||||
dmurph marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| </li> | ||||||
| <li>If |file_handler| is failure, continue. | ||||||
| </li> | ||||||
| <li>[=list/Append=] |file_handler| to |processedFileHandlers|. | ||||||
| </li> | ||||||
| </ol> | ||||||
| </li> | ||||||
| </ol> | ||||||
| <p> | ||||||
| On [=installation=], a user agent SHOULD register the file handlers | ||||||
|
There was a problem hiding this comment. I'm not sure what the technical definition of SHOULD is. For example, on Linux some of these things don't happen, i.e. we don't intend to support iconography on Linux. Does that fit within the definition of SHOULD? There was a problem hiding this comment. I think the "that are consistent with" here provides some wiggle room based on the OS. I'm not an expert in this though. There was a problem hiding this comment. I believe this language was suggested by @inexorabletash |
||||||
| with the operating system via interactions that are consistent with: | ||||||
| </p> | ||||||
| <ul> | ||||||
| <li>The [=file handler/icon=] and [=file handler/name=] appear in the | ||||||
| host operating system surfaces presenting options for opening files, | ||||||
| for example within "Open with..." context menus for associated file | ||||||
| types. | ||||||
| </li> | ||||||
| <li>The [=file handler/icon=] appears as the icon of associated files | ||||||
| in the host operating system. | ||||||
| </li> | ||||||
| <li>File types with multiple possible handlers can be disambiguated | ||||||
dmurph marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| by UX provided by the operating system. | ||||||
| </li> | ||||||
| </ul> | ||||||
| <p> | ||||||
| A user agent MAY prevent registered file handlers from registering as | ||||||
| the 'default' file handler for a given type if the operating system | ||||||
| allows. | ||||||
| </p> | ||||||
| <section data-cite="file-system-access"> | ||||||
| <h2> | ||||||
| <dfn>Execute a file handler launch</dfn> | ||||||
| </h2> | ||||||
| <p> | ||||||
| This is the IDL used for executing a file handling launch: | ||||||
| </p> | ||||||
| <pre class="idl"> | ||||||
| partial interface Window { | ||||||
| readonly attribute LaunchQueue launchQueue; | ||||||
| }; | ||||||
|
|
||||||
| callback LaunchConsumer = any (LaunchParams params); | ||||||
|
|
||||||
| [Exposed=Window] interface LaunchQueue { | ||||||
| undefined setConsumer(LaunchConsumer consumer); | ||||||
| }; | ||||||
|
|
||||||
| [Exposed=Window] interface LaunchParams { | ||||||
| readonly attribute FrozenArray<FileSystemHandle> files; | ||||||
| }; | ||||||
| </pre> | ||||||
| <p> | ||||||
| When a [=file type=] is registered with a web app and one or more | ||||||
| of these registered files are launched on the platform, run the | ||||||
| following steps, given the launched {{FrozenArray}} of | ||||||
| {{FileSystemHandle}}s |files:FrozenArray<FileSystemHandle>| | ||||||
| and the corresponding [=file handler|file_handler=]. | ||||||
| </p> | ||||||
| <ol> | ||||||
| <li>Let |url| be the |file_handler|.[=file handler/action=]. | ||||||
| </li> | ||||||
| <li>Let |browsing context| be the result of creating a new | ||||||
| [=top-level browsing context=]. | ||||||
| </li> | ||||||
| <li>[=Navigate=] |browsing context| to |url|. | ||||||
| </li> | ||||||
| <li>XXX Wait for navigation to be complete? | ||||||
dmurph marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| </li> | ||||||
| <li>Let |params:LaunchParams| be {{LaunchParams}} with | ||||||
| {{LaunchParams.files}} set to |files|. | ||||||
| </li> | ||||||
| <li>Iterate through every {{LaunchConsumer}} set by | ||||||
| {{LaunchQueue/setConsumer}} and execute the function with |params|. | ||||||
| </li> | ||||||
| </ol> | ||||||
| </section> | ||||||
| <section> | ||||||
| <h3> | ||||||
| Privacy consideration: Default [=file handler=]. | ||||||
dmurph marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| </h3> | ||||||
| <p> | ||||||
| Depending on the operating system capabilities, the [=manifest/file | ||||||
| handler=] could become a 'default' handler (e.g. handling launches | ||||||
| of a given file type automatically) of a given [=file type=] | ||||||
| without the explicit knowledge of the user. To protect against | ||||||
| possible mis-use, user agents MAY choose to offer the user the | ||||||
dmurph marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| functionality to not launch the web application, or even unregister | ||||||
| a given file handler for a web application. | ||||||
dmurph marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| </p> | ||||||
| </section> | ||||||
| <section> | ||||||
| <h3> | ||||||
| Privacy consideration: Name and icon. | ||||||
| </h3> | ||||||
| <p> | ||||||
| The name and icon of each file handler can be sensitive to privacy | ||||||
| and security, as there isn't a specified way for the user to see | ||||||
| and confirm these. Due to this, user agents MAY choose to replace | ||||||
| these with name and icon derived from the application's icon and | ||||||
dmurph marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| name in the [=process a file handler item=] algorithm. | ||||||
| </p> | ||||||
| </section> | ||||||
| </section> | ||||||
| <section> | ||||||
| <h2> | ||||||
| Manifest life-cycle | ||||||
|
|
@@ -1118,6 +1270,9 @@ <h3> | |||||
| <li>[=Process the `shortcuts` member=] passing |json|, |manifest|, | ||||||
| and |manifest URL|. | ||||||
| </li> | ||||||
| <li>[=Process the `file_handlers` member=] passing |json|, | ||||||
dmurph marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| |manifest|. | ||||||
| </li> | ||||||
| <li>[=application manifest/Processing extension-point=]: process | ||||||
| any proprietary and/or other supported members at this point in the | ||||||
| algorithm. | ||||||
|
|
@@ -1787,6 +1942,147 @@ <h2> | |||||
| </ol> | ||||||
| </section> | ||||||
| </section> | ||||||
| <section> | ||||||
| <h2> | ||||||
| File Handler Items | ||||||
| </h2> | ||||||
| <p> | ||||||
| Each <dfn data-local-lt="file handler's">file handler</dfn> represents | ||||||
|
There was a problem hiding this comment. Does ReSpec require the lt? Can you put the There was a problem hiding this comment. I'm matching how it works for shortcut items in this spec here. |
||||||
| a URL in the scope of the application that can handle launches with | ||||||
| [=file types=] it accepts. It has the following members: | ||||||
| </p> | ||||||
| <ul> | ||||||
| <li>[=file handler/action=] | ||||||
| </li> | ||||||
| <li>[=file handler/name=] | ||||||
| </li> | ||||||
| <li>[=file handler/accepts=] | ||||||
|
There was a problem hiding this comment. nit: accept (here and several other places) |
||||||
| </li> | ||||||
| <li>[=file handler/icons=] | ||||||
| </li> | ||||||
| </ul> | ||||||
| <p> | ||||||
| A user agent can use these members to associate the web application | ||||||
| with [=file type=] on the operating system. | ||||||
| </p> | ||||||
| <aside class="note"> | ||||||
| <p> | ||||||
|
There was a problem hiding this comment. This note sounds somewhat normative.... There was a problem hiding this comment. I've deleted this text because I believe the idea of it is covered by the normative text under #registering-file-handlers |
||||||
| The disambiguation of file handlers and selecting of default file | ||||||
dmurph marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| handlers is functionality left to the operating system. | ||||||
| </p> | ||||||
| </aside> | ||||||
| <section> | ||||||
| <h3> | ||||||
| `action` member | ||||||
| </h3> | ||||||
| <p> | ||||||
| The [=file handler's=] <code><dfn data-dfn-for= | ||||||
| "file handler">action</dfn></code> member is a <a>string</a> that | ||||||
| represents a relative URL of the [=manifest/start_url=] origin that | ||||||
|
There was a problem hiding this comment. This should probably be resolved relative to the manifest's URL instead (like other URLs in the manifest). |
||||||
| is [=manifest/within scope=] of a [=Document/processed manifest=]. | ||||||
| This URL will be navigated to in the steps to [=execute a file | ||||||
| handler launch=]. | ||||||
| </p> | ||||||
| </section> | ||||||
| <section> | ||||||
| <h3> | ||||||
| `name` member | ||||||
| </h3> | ||||||
| <p> | ||||||
| The [=file handler's=] <code><dfn data-dfn-for= | ||||||
| "file handler">name</dfn></code> member is a <a>string</a> that | ||||||
|
There was a problem hiding this comment. I think this should work:
Suggested change
There was a problem hiding this comment. This suggestion errors to be displayed whereas the current format works as expected. Is there a problem with the current format? |
||||||
| represents a name to be provided to the user's operating system for | ||||||
| use with "Open with..." UX flows. This MAY be replaced by the user | ||||||
dmurph marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| agent for privacy & security reasons. | ||||||
|
There was a problem hiding this comment. I'm not aware of privacy/security issues with the name member, did you have particular issues in mind? There was a problem hiding this comment. Hm.. can customize the text in window's explorer for a file type, right? It shows up as text on the OS, but maybe it's not an issue? "Infected File - Please Launch to Fix" or something else to encourage users to launch the file? IDK though - less direct than icon. |
||||||
| </p> | ||||||
| </section> | ||||||
| <section> | ||||||
| <h3> | ||||||
| `accept` member | ||||||
| </h3> | ||||||
| <p> | ||||||
| The [=file handler's=] <code><dfn data-dfn-for= | ||||||
| "file handler">accept</dfn></code> member is a <a>dictionary</a> | ||||||
| mapping [=MIME types=] to a list of extensions. Extensions have to be | ||||||
| strings that start with a "." and only contain [=valid suffix code | ||||||
| points=]. Additionally extensions are limited to a length of 16 code | ||||||
| points. | ||||||
| </p> | ||||||
| <p> | ||||||
| In addition to complete MIME types, "*" can be used as the subtype of | ||||||
|
There was a problem hiding this comment. should we link to the definition of a parseable mime type? Also, I don't think we want to handle mime type parameters, and it's worth noting that the type must be one of these: https://source.chromium.org/chromium/chromium/src/+/main:net/base/mime_util.cc;l=587-591?q=IsValidTopLevelMimeType&ss=chromium |
||||||
| a MIME type to match, for example, all image formats with "image/*". | ||||||
| </p> | ||||||
| <p> | ||||||
| Websites SHOULD always provide both [=MIME types=] and file | ||||||
|
There was a problem hiding this comment. Let me know what you think now |
||||||
| extensions for each accepts entry. This format is required by | ||||||
| operating systems that use [=MIME types=] to specify the [=file | ||||||
| types=]. On platforms that only use extensions, these can easily be | ||||||
| used instead. | ||||||
| </p> | ||||||
| </section> | ||||||
| <section> | ||||||
| <h3> | ||||||
| `icons` member | ||||||
| </h3> | ||||||
| <p> | ||||||
| The <a>file handler</a>'s <code><dfn data-dfn-for= | ||||||
| "file handler">icons</dfn></code> member lists images that serve as | ||||||
| graphical representations of a [=file type=] on a platform. This MAY | ||||||
| be replaced by the user agent for privacy & security reasons. | ||||||
| </p> | ||||||
| </section> | ||||||
| <section> | ||||||
| <h2> | ||||||
| Processing file handler items | ||||||
| </h2> | ||||||
| <p> | ||||||
| To <dfn>process a file handler item</dfn>, given [=ordered map=] | ||||||
| |item:ordered map|, [=URL=] |start_url:URL|, [=URL=] |scope:URL|, and | ||||||
| [=URL=] |manifest URL:URL|. | ||||||
| </p> | ||||||
| <ol class="algorithm"> | ||||||
| <li>Return failure if it's the case that: | ||||||
| <ul> | ||||||
| <li>|item| is not [=ordered map=]. | ||||||
| </li> | ||||||
| <li>|item|["action"] doesn't [=map/exist=] or is not a | ||||||
| [=string=]. | ||||||
| </li> | ||||||
| <li>|item|["name"] doesn't [=map/exist=] or is the empty string. | ||||||
|
|
||||||
| </li> | ||||||
| <li>|item|["accepts"] doesn't [=map/exist=]. | ||||||
| </li> | ||||||
| <li>|item|["accepts"] is not a [=sequence=]. | ||||||
| </li> | ||||||
| <li>|item|["accepts"] is an empty [=sequence=]. | ||||||
dmurph marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| </li> | ||||||
| </ul> | ||||||
| </li> | ||||||
| <li>Let |url:URL| be the result of [=URL Parser|parsing=] | ||||||
| |item|["action"] with |start_url URL| as the base URL. | ||||||
| </li> | ||||||
| <li>If |url| is failure, return failure. | ||||||
| </li> | ||||||
| <li>If |url| is not [=manifest/within scope=] of |scope|, return | ||||||
| failure. | ||||||
| </li> | ||||||
| <li>TODO - process "accepts" | ||||||
| </li> | ||||||
| <li>Let |file_handler:ordered map| be |ordered map| «[ "action" → | ||||||
| |url|, "name" → |item|["name"] ]». | ||||||
| </li> | ||||||
| <li>[=Process image resources=] passing |item|["icons"], | ||||||
| |file_handler|, |manifest URL|, and "icons". | ||||||
| </li> | ||||||
| <li>The user agent MAY replace |file_handler|["icons"] and | ||||||
| |file_handler|["name"] with the application icon and a string | ||||||
| containing the application name, respectively. | ||||||
dmurph marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| </li> | ||||||
| <li>Return |file_handler|. | ||||||
| </li> | ||||||
| </ol> | ||||||
| </section> | ||||||
| </section> | ||||||
| <section> | ||||||
| <h2> | ||||||
| External application resource | ||||||
|
|
||||||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
done.