A guideline for approving private script APIs in Blink-in-JS

[Kentaro Hara]

Hi

We are working on moving various features to Blink-in-JS, but most of the work are blocked by a discussion about what private script APIs (a.k.a, backdoors for private scripts) are approved [1][2][3][4]. Various people have various views on Blink-in-JS and thus it's hard to reach a consensus about it. We need to improve the situation because it is more important to move more things workable with fewer engineering resources.

Given the above, I write up a guideline about a process of approving private script APIs.

https://docs.google.com/a/google.com/document/d/1Uz-__hOTVRNqTiYEizRgAqjsaVT7bIbAx3Qml8Oh7e8/edit

In short, the proposed guideline is as follows:

- You need to get an LGTM from one API owner.

- A private script API is allowed if it meets either of the following conditions:

(A) The API is considered to be a missing bit of the current web platform. The API is considered to be exposed to the web in the future.

(B) The API is a temporary one. It is considered that temporarily allowing the API is a good decision to move the Blink-in-JS work forward with fewer engineering resources. In this case, there must be a concrete plan about how the API is going to be removed/replaced in the future.

Comments are appreciated :)

===================

[1] HTMLPlaceHolderElement: https://codereview.chromium.org/516273002/

[2] HTMLMarqueeElement: https://codereview.chromium.org/634843002/

[3] XMLSerializer: https://codereview.chromium.org/534583002/

[4] ProcessingInstruction: https://codereview.chromium.org/365873002/

--
Kentaro Hara, Tokyo, Japan

[Jochen Eisinger]

Hey,

thanks for writing this up.

I added a bunch of comments to the document. In short, I think we should concentrate on moving features that we don't consider first-class citizens to blink-in-js, such as XSLT.

If those features need a private API, those APIs are unlikely to be ever exposed to the web platform, nor are they temporary. Still, we will need to add them.

The other goal you mention (talking to mojo services) might also require private APIs that will stick around, and that's ok.

I don't want to add temporary APIs - if we don't want to have them in the end, just don't add them.

best

-jochen

[Kentaro Hara]

If those features need a private API, those APIs are unlikely to be ever exposed to the web platform, nor are they temporary. Still, we will need to add them.

So if a private script API is needed to move second-class citizens to Blink-in-JS, do you think that it is OK to approve the private script API?

I think that's something abarth@ and esprehn@ want to avoid. I also think that we shouldn't add random private script APIs even if the APIs are for second-class citizens, because one of the goals of Blink-in-JS is to make the web layering better. That's why we abandoned MediaControls-in-JS (because it requires intrusive private script APIs). The key part of VTT-in-JS is also how to factor out VTT from C++ without adding intrusive private script APIs.

I don't want to add temporary APIs - if we don't want to have them in the end, just don't add them.

That would depend on a meaning of "temporary", but my point is that I want to avoid a situation where we have to block Blink-in-JS work until we fix some web-exposed APIs, we get full use counters from the wild, we implement a new resource scheme like chrome-resource:// etc. The CLs I listed in the first email are blocked by such situations. They know an ideal solution which doesn't require private script APIs, but it takes time to get there, so they want to add private script APIs temporarily.

(That being said, you won't need to buy this discussion because if you simply approve private script APIs for second-class citizens, you can approve all private script APIs in those CLs. Thus the problem doesn't exist anymore (without discussing whether we should allow temporary APIs or not).)

[Glenn Adams]

On Fri, Oct 17, 2014 at 1:30 AM, Kentaro Hara <har...@chromium.org> wrote:

If those features need a private API, those APIs are unlikely to be ever exposed to the web platform, nor are they temporary. Still, we will need to add them.

So if a private script API is needed to move second-class citizens to Blink-in-JS, do you think that it is OK to approve the private script API?

I think that's something abarth@ and esprehn@ want to avoid. I also think that we shouldn't add random private script APIs even if the APIs are for second-class citizens, because one of the goals of Blink-in-JS is to make the web layering better. That's why we abandoned MediaControls-in-JS (because it requires intrusive private script APIs). The key part of VTT-in-JS is also how to factor out VTT from C++ without adding intrusive private script APIs.

A possible way to do the latter is to implement an "HTMLCue" interface on the C++ side, which has the HTML fragment rendering of the VTTCue as its content. Then the VTT-in-JS side can focus on parsing and converting each cue to an HTML fragment and the C++ side focuses upon rendering the HTMLCue instances.

 

To unsubscribe from this group and stop receiving emails from it, send an email to blink-dev+...@chromium.org.

[Jochen Eisinger]

On Fri Oct 17 2014 at 9:31:10 AM Kentaro Hara <har...@chromium.org> wrote:

If those features need a private API, those APIs are unlikely to be ever exposed to the web platform, nor are they temporary. Still, we will need to add them.

So if a private script API is needed to move second-class citizens to Blink-in-JS, do you think that it is OK to approve the private script API?

Yes...

 

I think that's something abarth@ and esprehn@ want to avoid. I also think that we shouldn't add random private script APIs even if the APIs are for second-class citizens, because one of the goals of Blink-in-JS is to make the web layering better. That's why we abandoned MediaControls-in-JS (because it requires intrusive private script APIs). The key part of VTT-in-JS is also how to factor out VTT from C++ without adding intrusive private script APIs.

...unless of course, the APIs become to intrusive.

But I think moving XSLT out of blink is worth some private APIs

 

I don't want to add temporary APIs - if we don't want to have them in the end, just don't add them.

That would depend on a meaning of "temporary", but my point is that I want to avoid a situation where we have to block Blink-in-JS work until we fix some web-exposed APIs, we get full use counters from the wild, we implement a new resource scheme like chrome-resource:// etc. The CLs I listed in the first email are blocked by such situations. They know an ideal solution which doesn't require private script APIs, but it takes time to get there, so they want to add private script APIs temporarily.

If the right thing to do takes more time, we should take the time.

 

(That being said, you won't need to buy this discussion because if you simply approve private script APIs for second-class citizens,

you can approve all private script APIs in those CLs. Thus the problem doesn't exist anymore (without discussing whether we should allow temporary APIs or not).)

A private API should be the last resort, not a shortcut.

[Kentaro Hara]

So Jochen's suggestion is:

- A private script API is allowed if the API is needed for moving second-class citizens to Blink-in-JS. (Of course, the private script API is the last resort and we should try our best to avoid it.)

I agree that this rule will definitely solve the problem we want to solve now (i.e., the problem that XSLT-in-JS, marquee-in-JS, execCommand-in-JS and VTT-in-JS are blocked by private script APIs), but I'm a bit afraid that if we adopt the rule, we will end up with producing a lot of random private script APIs. It will contribute to factoring out second-class features from C++ but won't contribute to making the web layering better.

Probably we can wait Adam, Elliott or others to chime in :)

[Jochen Eisinger]

On Fri Oct 17 2014 at 10:00:36 AM Kentaro Hara <har...@chromium.org> wrote:

So Jochen's suggestion is:

- A private script API is allowed if the API is needed for moving second-class citizens to Blink-in-JS. (Of course, the private script API is the last resort and we should try our best to avoid it.)

Also, I only consider XSLT to be a second-class citizen out of the examples you provided.

 

If an API is "temporary" as in, there's a better solution that takes longer, we should go for the better solution always.

best

-jochen

[Kentaro Hara]

Also, I only consider XSLT to be a second-class citizen out of the examples you provided.

You think that XSLT and Mojo are good goals but execCommand and marquee are not good goals. On the other hand, people who are actually maintaining editing/ think that execCommand in C++ is a big pain and execCommand-in-JS is a worth. We have to respect views of various people because Blink is an open platform. Thus it wouldn't make sense to define a guideline in such a too specific (biased) way that private script APIs are allowed if the APIs are needed for to-be-deprecated features and Mojo.

Blink-in-JS is a new technology and I don't think it's a good idea to limit the goals at this point. There are multiple potential advantages in Blink-in-JS, even though some of them won't be seen as advantages to some people. I think what we should do here is to build up a good guideline to move Blink-in-JS work forward, rather than expressing personal thoughts about what should be OK and what should not be OK.

Here is another suggestion of the guideline:

- Send an Intent-to-implement to blink-dev@ when you want to implement a feature in Blink-in-JS. The Intent-to-implement should describe the advantages of implementing the feature in Blink-in-JS.

- Once it's approved, unavoidable private script APIs are allowed to implement the Blink-in-JS.

What do you think?

[Jochen Eisinger]

That is fine, however, I don't see how this will make a big difference whether I disagree on this thread, or on the intent-to-implement threads.

[Takashi Sakamoto]

2014-10-17 17:46 GMT+09:00 Jochen Eisinger <joc...@chromium.org>

 

If an API is "temporary" as in, there's a better solution that takes longer, we should go for the better solution always.

So if adding the temporary API is on the way to the better solution, we should not allow the API?

I think, sometimes there are several ways to reach the better solution.

So if we can quickly make Blink simpler by adding some temporary API, I think, other developers will be happy (e.g. StyleEngine and XSLT), because they don't need to maintain the feature.

When we have enough use counter data, we will remove the temporary API or will change the temporary API to be exposed Web API. The follow-up task will not affect other developers (e.g. because of just XSLT issue).

I would like to know what you think about this.

[Kentaro Hara]

That is fine, however, I don't see how this will make a big difference whether I disagree on this thread, or on the intent-to-implement threads.

It's fine you disagree with (for example) execCommand-in-JS. If majority of the Blink people have the same thought, we should stop the work. Otherwise, we can proceed with the work.

I'm not intending to convince you about execCommand-in-JS. I'm intending to solve a problem that multiple people are actually blocked in Blink-in-JS work because the decision-making process is unclear. I think it is helpful to have a good rule to decide go or non-go, and if it is go, there should be a way to support smooth development.

[Jochen Eisinger]

If we're talking about a general policy, then no, we should not allow this.

If we're looking at APIs on a case-by-case basis, as Kentaro suggests in his last mail, then we can have a closer look. But the baseline should be "no temporary APIs".

best

-jochen 

[Jochen Eisinger]

On Fri Oct 17 2014 at 12:12:35 PM Kentaro Hara <har...@chromium.org> wrote:

That is fine, however, I don't see how this will make a big difference whether I disagree on this thread, or on the intent-to-implement threads.

It's fine you disagree with (for example) execCommand-in-JS. If majority of the Blink people have the same thought, we should stop the work. Otherwise, we can proceed with the work.

I'm not intending to convince you about execCommand-in-JS. I'm intending to solve a problem that multiple people are actually blocked in Blink-in-JS work because the decision-making process is unclear. I think it is helpful to have a good rule to decide go or non-go, and if it is go, there should be a way to support smooth development.

That sounds reasonable.

It will be easier to assess concrete proposals than coming up with a generally agreed upon policy.

best

-jochen

[Kentaro Hara]

Thanks all for comments!

Let me sum up the discussion so far. I think that a proposal of the guideline is as follows:

- When you want to implement a feature in Blink-in-JS, you need to send an Intent-to-implement to blink-dev@. The Intent-to-implement should describe the advantages of implementing the feature in Blink-in-JS.

- When implementing the feature in Blink-in-JS, you need to try your best not to depend on private script APIs. If private script APIs are unavoidable, you need to get an LGTM from one API owner.

[Jochen Eisinger]

should we include the APIs you want to use in the intent-to-implement?

[Kentaro Hara]

should we include the APIs you want to use in the intent-to-implement?

Sounds nice!

(Actually it's hard to notice the need of private script APIs until you actually implement the feature in JS and hit weird edge-case behavior of the web :-)

[Jochen Eisinger]

sure, but if you already expect to need some, just include them :)

[Elliott Sprehn]

I don't think we should be adding any extra APIs. Down that path leads madness and the same messes we're trying to prevent by moving certain features into Blink-in-JS. I _do_ think we should move the media controls into Blink-in-JS, whatever APIs are missing we should add to the web platform. Please send emails to public-webapps so we can make that happen.

[Kentaro Hara]

I chatted with a couple of folks offline. We're all in agreement in that Blink-in-JS is a good thing if it doesn't require any private script API. We need a good guideline about private script APIs. We need to balance the following two facts:

- We should not mess up the platform by adding private script APIs. A private script API is a bad thing in both philosophy and practice.

- We should move Blink-in-JS work forward with fewer engineering resources. It is not productive to spend a lot of time in moving will-be-deprecated features to Blink-in-JS.

Here is a revised version of the guideline:

====================

- If you plan to implement a feature in Blink-in-JS, you need to send an intent-to-implement to blink-dev@ and get a consensus.

- You need to try your best to implement Blink-in-JS without relying on private script APIs. If you really need to add a private script API, you need to get an LGTM from one API owner. The private script API must meet either of the following conditions:

(a) The private script API is a missing part of the current web and going to be exposed to the web in the future.

(b) The private script API is for supporting a will-be-deprecated feature.

====================

The revised guideline is more strict than the one I proposed based on the discussion with jochen. Even if we are in agreement on moving a feature to Blink-in-JS, a private script API is not approved unless the API meets either of the above conditions.

The condition (a) is needed not to block Blink-in-JS work until the API is actually exposed to the web. One example is Element.createUserAgentShadowRoot(). It is clear that we cannot implement built-in elements (like <marquee>) without having a way to create a private shadow root. Otherwise, the contents of the shadow root are exposed to the web. Thus

Element.createUserAgentShadowRoot() is considered to be a missing part of the current web. However, historically speaking, we rejected the idea of having an API to create a private shadow root as a result of a ton of discussions about the shadow DOM spec. Given the history, it wouldn't be that easy to actually expose the API to the web in a reasonable timeline. We should definitely give the feedback to the working group or public-webapps@ but don't want to block the Blink-in-JS work until the API is actually exposed to the web.

The condition (b) is needed to move features Blink wants to deprecate but cannot deprecate right away to Blink-in-JS. XSLT is a good example for this, and we need ProcessingInstruction.onProcessingInstructionAvailable() to implement XSLT-in-JS. The API is considered to be a missing part of the web platform to implement something like XSLT, but clearly, it doesn't make sense to try to expose the API to the web because we want to deprecate XSLT. What we should do here is to deprecate XSLT instead of exposing the API to support XSLT. The condition (b) covers such cases.

Another thing we need to care about is how to handle APIs for Blink specific purposes. For example, execCommand-in-JS wants an API for UseCounter. UseCounter is a notion of Blink and not a part of the web. Another example is APIs that will be added to connect Blink-in-JS with Mojo. These APIs are not a part of the web either. I think these APIs are out of the scope of private script APIs and should be added to utility functions of PrivateScriptRunner (which already provides basic functionality for private scripts; e.g., installClass, DOMException, JSError etc). These APIs are not part of IDL files and thus doesn't need to meet the conditions described above.

What do you think?

[Dimitri Glazkov]

On Wed, Oct 22, 2014 at 8:43 AM, Kentaro Hara <har...@chromium.org> wrote:

I chatted with a couple of folks offline. We're all in agreement in that Blink-in-JS is a good thing if it doesn't require any private script API. We need a good guideline about private script APIs. We need to balance the following two facts:

- We should not mess up the platform by adding private script APIs. A private script API is a bad thing in both philosophy and practice.

- We should move Blink-in-JS work forward with fewer engineering resources. It is not productive to spend a lot of time in moving will-be-deprecated features to Blink-in-JS.

Here is a revised version of the guideline:

====================

- If you plan to implement a feature in Blink-in-JS, you need to send an intent-to-implement to blink-dev@ and get a consensus.

- You need to try your best to implement Blink-in-JS without relying on private script APIs. If you really need to add a private script API, you need to get an LGTM from one API owner. The private script API must meet either of the following conditions:

(a) The private script API is a missing part of the current web and going to be exposed to the web in the future.

(b) The private script API is for supporting a will-be-deprecated feature.

====================

The revised guideline is more strict than the one I proposed based on the discussion with jochen. Even if we are in agreement on moving a feature to Blink-in-JS, a private script API is not approved unless the API meets either of the above conditions.

The condition (a) is needed not to block Blink-in-JS work until the API is actually exposed to the web. One example is Element.createUserAgentShadowRoot(). It is clear that we cannot implement built-in elements (like <marquee>) without having a way to create a private shadow root. Otherwise, the contents of the shadow root are exposed to the web. Thus

Element.createUserAgentShadowRoot() is considered to be a missing part of the current web. However, historically speaking, we rejected the idea of having an API to create a private shadow root as a result of a ton of discussions about the shadow DOM spec. Given the history, it wouldn't be that easy to actually expose the API to the web in a reasonable timeline. We should definitely give the feedback to the working group or public-webapps@ but don't want to block the Blink-in-JS work until the API is actually exposed to the web.

Errr.. I was with you until this paragraph :)

FWIW, This is just a straight matter of fixing https://www.w3.org/Bugs/Public/show_bug.cgi?id=20144. There's wide consensus in public-webapps that closed shadow trees are a useful primitive.

[Kentaro Hara]

> The condition (a) is needed not to block Blink-in-JS work until the API is actually exposed to the web. One example is Element.createUserAgentShadowRoot(). It is clear that we cannot implement built-in elements (like <marquee>) without having a way to create a private shadow root. Otherwise, the contents of the shadow root are exposed to the web. Thus
> Element.createUserAgentShadowRoot() is considered to be a missing part of the current web. However, historically speaking, we rejected the idea of having an API to create a private shadow root as a result of a ton of discussions about the shadow DOM spec. Given the history, it wouldn't be that easy to actually expose the API to the web in a reasonable timeline. We should definitely give the feedback to the working group or public-webapps@ but don't want to block the Blink-in-JS work until the API is actually exposed to the web.

Errr.. I was with you until this paragraph :)
FWIW, This is just a straight matter of fixing https://www.w3.org/Bugs/Public/show_bug.cgi?id=20144. There's wide consensus in public-webapps that closed shadow trees are a useful primitive.

Oh, that's great news! :)

The key point here would be whether it is allowed to add Element.createUserAgentShadowRoot() as a private script API and move marquee-in-JS forward instead of fixing https://www.w3.org/Bugs/Public/show_bug.cgi?id=20144 (assuming that fixing the bug is a substantial amount of work).

[Dimitri Glazkov]

On Wed, Oct 22, 2014 at 8:54 AM, Kentaro Hara <har...@chromium.org> wrote:

> The condition (a) is needed not to block Blink-in-JS work until the API is actually exposed to the web. One example is Element.createUserAgentShadowRoot(). It is clear that we cannot implement built-in elements (like <marquee>) without having a way to create a private shadow root. Otherwise, the contents of the shadow root are exposed to the web. Thus
> Element.createUserAgentShadowRoot() is considered to be a missing part of the current web. However, historically speaking, we rejected the idea of having an API to create a private shadow root as a result of a ton of discussions about the shadow DOM spec. Given the history, it wouldn't be that easy to actually expose the API to the web in a reasonable timeline. We should definitely give the feedback to the working group or public-webapps@ but don't want to block the Blink-in-JS work until the API is actually exposed to the web.

Errr.. I was with you until this paragraph :)
FWIW, This is just a straight matter of fixing https://www.w3.org/Bugs/Public/show_bug.cgi?id=20144. There's wide consensus in public-webapps that closed shadow trees are a useful primitive.

Oh, that's great news! :)

The key point here would be whether it is allowed to add Element.createUserAgentShadowRoot() as a private script API and move marquee-in-JS forward instead of fixing https://www.w3.org/Bugs/Public/show_bug.cgi?id=20144 (assuming that fixing the bug is a substantial amount of work).

My answer would be this: if there's a plan to work on the spec and rapidly deprecate createUserAgentShadowRoot, then definitely yes. Otherwise, we are shifting our debt from one credit card to another. Which might be a good thing (lower interest, etc.), but it's not clear in general case.

:DG<

[Jochen Eisinger]

Right, introducing private APIs with this reasoning is just piling up technical debt.

Yes, it is blocking some projects. But if the platform is not good enough to allow for implementing these features on top of it, I'd claim it's a higher priority to fix the platform than to proceed with these projects.

 

:DG<

[Jochen Eisinger]

On Wed Oct 22 2014 at 5:43:35 PM Kentaro Hara <har...@chromium.org> wrote:

I chatted with a couple of folks offline. We're all in agreement in that

I want to encourage everybody to participate in this public discussion.

 

Blink-in-JS is a good thing if it doesn't require any private script API. We need a good guideline about private script APIs. We need to balance the following two facts:

- We should not mess up the platform by adding private script APIs. A private script API is a bad thing in both philosophy and practice.

- We should move Blink-in-JS work forward with fewer engineering resources. It is not productive to spend a lot of time in moving will-be-deprecated features to Blink-in-JS.

Here is a revised version of the guideline:

====================

- If you plan to implement a feature in Blink-in-JS, you need to send an intent-to-implement to blink-dev@ and get a consensus.

With the reasoning above, should this be an intent to deprecate instead?

 

- You need to try your best to implement Blink-in-JS without relying on private script APIs. If you really need to add a private script API, you need to get an LGTM from one API owner. The private script API must meet either of the following conditions:

(a) The private script API is a missing part of the current web and going to be exposed to the web in the future.

We should not add such APIs

 

(b) The private script API is for supporting a will-be-deprecated feature.

====================

The revised guideline is more strict than the one I proposed based on the discussion with jochen. Even if we are in agreement on moving a feature to Blink-in-JS, a private script API is not approved unless the API meets either of the above conditions.

The condition (a) is needed not to block Blink-in-JS work until the API is actually exposed to the web. One example is Element.createUserAgentShadowRoot(). It is clear that we cannot implement built-in elements (like <marquee>) without having a way to create a private shadow root. Otherwise, the contents of the shadow root are exposed to the web. Thus

Element.createUserAgentShadowRoot() is considered to be a missing part of the current web. However, historically speaking, we rejected the idea of having an API to create a private shadow root as a result of a ton of discussions about the shadow DOM spec. Given the history, it wouldn't be that easy to actually expose the API to the web in a reasonable timeline. We should definitely give the feedback to the working group or public-webapps@ but don't want to block the Blink-in-JS work until the API is actually exposed to the web.

The condition (b) is needed to move features Blink wants to deprecate but cannot deprecate right away to Blink-in-JS. XSLT is a good example for this, and we need ProcessingInstruction.onProcessingInstructionAvailable() to implement XSLT-in-JS. The API is considered to be a missing part of the web platform to implement something like XSLT, but clearly, it doesn't make sense to try to expose the API to the web because we want to deprecate XSLT. What we should do here is to deprecate XSLT instead of exposing the API to support XSLT. The condition (b) covers such cases.

Another thing we need to care about is how to handle APIs for Blink specific purposes. For example, execCommand-in-JS wants an API for UseCounter. UseCounter is a notion of Blink and not a part of the web.

Last time this was discussed, we reached the conclusion to not add an API for this.

 

Another example is APIs that will be added to connect Blink-in-JS with Mojo. These APIs are not a part of the web either. I think these APIs are

That can be done with navigator.connect()

[Kentaro Hara]

> ====================
> - If you plan to implement a feature in Blink-in-JS, you need to send an intent-to-implement to blink-dev@ and get a consensus.

With the reasoning above, should this be an intent to deprecate instead?

Not really. As discussed above, the goal of Blink-in-JS is not limited to will-be-deprecated features. execCommand-in-JS is one example (even though you disagree with it), and Mojo-with-Blink-in-JS would be another example.

> - You need to try your best to implement Blink-in-JS without relying on private script APIs. If you really need to add a private script API, you need to get an LGTM from one API owner. The private script API must meet either of the following conditions:
>
> (a) The private script API is a missing part of the current web and going to be exposed to the web in the future.

We should not add such APIs

> Yes, it is blocking some projects. But if the platform is not good enough to allow for implementing these features on top of it, I'd claim it's a higher priority to fix the platform than to proceed with these projects.

I agree with you that that is the world we should reach in the end, but it is important to get to the world in the fastest path. In that sense:

- proposing a missing API to the web while working on Blink-in-JS in parallel with a (temporary) private script API

seems better than:

- just blocking the Blink-in-JS work until the API is actually exposed.

Thus I agree with the following Dimitri's thought:

> My answer would be this: if there's a plan to work on the spec and rapidly deprecate createUserAgentShadowRoot, then definitely yes. Otherwise, we are shifting our debt from one credit card to another. Which might be a good thing (lower interest, etc.), but it's not clear in general case.

I guess you're limiting the goal of Blink-in-JS to will-be-deprecated features (and Mojo) and going to allow private script APIs only if the APIs are for will-be-deprecated features. However, I'd argue that that approach won't contribute to find a missing part of the current web and improve it. Finding a missing part and exposing it to the web is one of the important goals of Blink-in-JS, as Dimitri, Adam and Elliott mentioned.

For example, XSLT-in-JS needs Window.replaceDocument() (or something like that; see the discussion in https://codereview.chromium.org/365873002/). We consider that Window.replaceDocument() is a missing part of the current web, not just for supporting XSLT features. In your proposal, you will accept Window.replaceDocument() because "XSLT is a will-be-deprecated feature. Window.replaceDocument() is needed to move the will-be-deprecated feature. Thus it's OK to accept". However, I think it is more constructive to consider "Window.replaceDocument() is a missing part of the web. Let's propose the API while working on Blink-in-JS with a private script API until the API is actually exposed" in order to evolve the web platform.

> Another thing we need to care about is how to handle APIs for Blink specific purposes. For example, execCommand-in-JS wants an API for UseCounter. UseCounter is a notion of Blink and not a part of the web. 

 

Last time this was discussed, we reached the conclusion to not add an API for this.

We didn't really reach any conclusion. UseCounter APIs are not mandatory to make execCommand-in-JS workable (we just cannot get metric of execCommand-in-JS), so we've just deferred the discussion to later. The editing team still needs UseCounters.

Here I'm not intending to discuss whether we should add UseCounter APIs or not specifically. I just want to mention that APIs that are not part of IDL files (e.g., UseCounters, some APIs of Mojo if they need any) are out of the scope of private script APIs and thus can be added to PrivateScriptRunner as a basic functionality of Blink-in-JS infrastructure.

I hope more folks (especially who are getting involved in actual Blink-in-JS work) get involve in this discussion :-)

On Sun, Oct 19, 2014 at 9:04 AM, Elliott Sprehn <esp...@chromium.org> wrote:t

[Rick Byers]

On Wed, Oct 22, 2014 at 9:50 PM, Kentaro Hara <har...@chromium.org> wrote:

> ====================
> - If you plan to implement a feature in Blink-in-JS, you need to send an intent-to-implement to blink-dev@ and get a consensus.

With the reasoning above, should this be an intent to deprecate instead?

Not really. As discussed above, the goal of Blink-in-JS is not limited to will-be-deprecated features. execCommand-in-JS is one example (even though you disagree with it), and Mojo-with-Blink-in-JS would be another example.

> - You need to try your best to implement Blink-in-JS without relying on private script APIs. If you really need to add a private script API, you need to get an LGTM from one API owner. The private script API must meet either of the following conditions:
>
> (a) The private script API is a missing part of the current web and going to be exposed to the web in the future.

We should not add such APIs

> Yes, it is blocking some projects. But if the platform is not good enough to allow for implementing these features on top of it, I'd claim it's a higher priority to fix the platform than to proceed with these projects.

I agree with you that that is the world we should reach in the end, but it is important to get to the world in the fastest path. In that sense:

In particular, we've got the opportunity with Blink-in-JS for a virtuous cycle where we can experiment with variations on new platform APIs and learn from those experiments before committing ourselves forever to the API.

Other platforms benefit from a co-evolution of the kernel and frameworks, but accomplish it by shipping major new versions only every couple years - giving plenty of time to evolve the framework and kernel together until committing to a new kernel API.

In Chrome we rely on experimental RuntimeEnabledFeatures to do this while maintaining a regular ship cadence.  Web components certainly benefited from being able to evolve Polymer and blink together (by testing polymer with experimental web platform features enabled).  Copying the polymer strategy exactly would mean we implement blink-in-js features twice - once relying on experimental web platform features when they're available, and second as some sort of limited polyfill.  But in this case there's no value in doing the 2nd implementation - there's no compat risk with blink-in-js taking a dependency on an experimental feature.

So, perhaps the policy can just be that blink-in-JS is free to make use of experimental web platform features?  But, as always (and perhaps with some extra discipline), experimental platform feature should either be on a clear path to shipping or being deleted.

[Kentaro Hara]

So, perhaps the policy can just be that blink-in-JS is free to make use of experimental web platform features?  But, as always (and perhaps with some extra discipline), experimental platform feature should either be on a clear path to shipping or being deleted.

+1

Jochen, what's your opinion on the following guideline (this is the same one I posted two days ago)?

====================

- If you plan to implement a feature in Blink-in-JS, you need to send an intent-to-implement to blink-dev@ and get a consensus.

- You need to try your best to implement Blink-in-JS without relying on private script APIs. If you really need to add a private script API, you need to get an LGTM from one API owner. The private script API must meet either of the following conditions:

(a) The private script API is a missing part of the current web and going to be exposed to the web in the future.

(b) The private script API is for supporting a will-be-deprecated feature.

====================

This guideline is more strict than the one you agreed on one week ago (the previous one didn't have the condition (a) and (b)), so I don't fully see a reason you don't like it. If you have any concern, I'm fine with deferring the discussion to BlinkOn so that we can discuss offline. Otherwise I'll ask people working on Blink-in-JS to send an Intent-to-Implement.

[Jochen Eisinger]

I agree that having an intent to implement email is a good thing, however, I will push back against private APIs that satisfy (a):

- I think we should not invest effort into adding private APIs for missing web features, we should invest effort into implementing missing web features

- For experimenting with or learning about the platform, we should use branches, and not trunk.

I like the idea behind Rick's proposal to use experimental APIs, however, in practice I fear this will lead to code explosion in bindings.

Should we take one of the remaining free slots at blinkon3 so everybody interested can join the discussion?

best

-jochen

[Kentaro Hara]

Should we take one of the remaining free slots at blinkon3 so everybody interested can join the discussion?

Sounds like a good idea. I'll schedule it.

[Mike West]

On Fri, Oct 24, 2014 at 8:55 AM, Jochen Eisinger <joc...@chromium.org> wrote:

I agree that having an intent to implement email is a good thing, however, I will push back against private APIs that satisfy (a):

- I think we should not invest effort into adding private APIs for missing web features, we should invest effort into implementing missing web features

+1.

 

- For experimenting with or learning about the platform, we should use branches, and not trunk.

Hrm. What's the bar here? My impression is that we've been pretty lax with our intent to implement process; when should something bake on a branch before landing in trunk?

 

I like the idea behind Rick's proposal to use experimental APIs, however, in practice I fear this will lead to code explosion in bindings.

Using experimental APIs that we actually intend to ship seems pretty reasonable. It's a good way to gain implementation experience with those APIs without exposing them to the web, which I think would give us more confidence that the APIs actually do the things we need them to do.

My worry would be that we'd add experimental APIs that we aren't confidently planning to ship, just because it makes implementing some feature in JavaScript easier than it would otherwise be. We're doing a fairly good job of keeping our runtime-enabled feature list short in Blink; as long as that remains the case, this risk seems reasonable to take.

-mike

[Philip Jägenstedt]

Yes, moving media controls out of C++ is definitely something we
should do, and in fact WebKit has already done it. The tracking bug is
https://crbug.com/399821 and I've commented about some specifics.

Philip

> To unsubscribe from this group and stop receiving emails from it, send an
> email to blink-dev+...@chromium.org.

[Rick Byers]

There's risk in the other direction too.  When we implement high-level features in C++ with hooks into whatever system reviewers will tolerate, we can deceive ourselves into thinking it's OK with arguments like "frameworks should never need this ability - this code is special".  If we make the bar too high, people will just avoid using blink-in-js and further exacerbate the monolithic nature of our platform and code base.

Instead I hope we can strike a good balance that encourages people to try to build their feature on top of primitives, and incrementally works towards refining those primitives into part of web platform.  That can help advance the platform in ways we might not predict (a "special case" often turns out not to be so special after discussion with people who see related special cases).  I've seen this process be pretty valuable in other traditional platforms (eg. co-evolution of the windows kernel with applications/frameworks).

Perhaps we should have a formal process where the API owners drive a review of every RuntimeEnabledFeature once a quarter (or f2f at every BlinkOn), and ensures there's someone signed up to actively move each feature along?  In extreme cases we can have volunteers rip out abandoned/stalled features (which could also mean rewriting a poorly planned blink-in-js feature as C++). Something like this would be healthy regardless of what we decide about blink-in-js.

-mike

[Jeremy Roman]

The perfect is the enemy of the good. It would be wonderful to have
Blink-in-JS features use only public web APIs, but I’m not sure that’s
always realistic.


In particular, I'm concerned that these guidelines would strongly
discourage implementing a feature on Blink-in-JS for reason (d) in the
linked document ("hackability"). It could make doing so unnecessarily:

- risky (the developer assumes a risk of being told to reimplement
functionality in C++ the moment this line is crossed), and

- arduous (a vetting process like this is not required for other APIs
between classes in Blink when both are implemented in C++; why is it
different when one is implemented in private script?)


We should, of course, consider when implementing a feature whether we
have identified gaps in the web platform. If we have, we should pursue
a web-exposed API to fill that gap, and if possible we should move our
own features to use the same standard infrastructure once it exists.
But I don't see why we need to block implementation of the feature on
the standard solution; if the API is private to Blink, we can change
every call site in a single CL. I'm not sure I see the advantage of
this "use only public JS APIs or only private C++ APIs" dichotomy.


For instance, I'm working on moving plugin placeholders to shadow DOM,
and it was suggested that I implement these on top of Blink-in-JS.
It's mostly a matter of presenting a message (“The Java plugin is
disabled.”, etc.) from the embedder, but it needs to be able to call
back to the browser. Is there a substantive difference between that
calling a "private API" to a C++ method that performs the action and
calling a "listener" VoidCallback supplied by C++? They both look like
"this.doSomething();" in script. The first is simpler to implement,
though. (somewhat more detail here
https://docs.google.com/document/d/16StE2oGR2O2MNwfEzZYKlg-3KRmYH-EioEJVhDvmQ2M/edit?usp=sharing
; design doc available on request). It's worth noting that this
feature is more of a browser feature than a platform feature (the
user, not the author, controls click-to-play, disabled plugins, etc.).


I think the bar should be lower for APIs which have a small impact on
the platform, like:

- Element.createUserAgentShadowRoot (which is very similar to
createShadowRoot, and exercises a capability we already rely on for
other features),

- UseCounter (which is useful elsewhere in Blink and Chromium, and for
which an alternate implementation could easily be supplied by someone
else), and

- callbacks to a C++ class which logically "owns" the Blink-in-JS one
(for instance, someone who wanted to reuse the shadow DOM plugin
placeholder code could map these to whatever behaviour they desired)


I don't think having private APIs such as these causes divergence from
the open web platform. The first points to a gap we may be able to
fill later on, the second fills a need that is already met in the web
platform (cf. any web analytics tool, XHR, Beacon), and the third is
just an object/client relationship that happens to look a little
different because one side is written in C++.


I'm also not sure I understand how Mojo fits into this discussion. I
may be missing context, but it sounds like we're saying "private
bindings are bad, but private Mojo services are good". I'm not sure
what the difference is here, except that one is declared in a .idl
file and the other in a .mojom file, one is located through property
access and the other through navigator.connect, etc.

On Wed, Oct 22, 2014 at 9:50 PM, Kentaro Hara <har...@chromium.org> wrote:
>> > ====================
>> > - If you plan to implement a feature in Blink-in-JS, you need to send an
>> > intent-to-implement to blink-dev@ and get a consensus.
>>
>> With the reasoning above, should this be an intent to deprecate instead?
>
>
> Not really. As discussed above, the goal of Blink-in-JS is not limited to
> will-be-deprecated features. execCommand-in-JS is one example (even though
> you disagree with it), and Mojo-with-Blink-in-JS would be another example.
>
>

>> > - You need to try your best to implement Blink-in-JS without relying on
>> > private script APIs. If you really need to add a private script API, you
>> > need to get an LGTM from one API owner. The private script API must meet

>> > either of the following conditions:
>> >

>> > (a) The private script API is a missing part of the current web and

>> > going to be exposed to the web in the future.

>>
>> We should not add such APIs
>
>
>> Yes, it is blocking some projects. But if the platform is not good enough
>> to allow for implementing these features on top of it, I'd claim it's a
>> higher priority to fix the platform than to proceed with these projects.
>
> I agree with you that that is the world we should reach in the end, but it
> is important to get to the world in the fastest path. In that sense:
>

> On Thu, Oct 23, 2014 at 3:00 AM, Jochen Eisinger <joc...@chromium.org>
> wrote:
>>
>>
>>
>> On Wed Oct 22 2014 at 5:43:35 PM Kentaro Hara <har...@chromium.org>

>> wrote:
>>>
>>> I chatted with a couple of folks offline. We're all in agreement in that
>>
>>
>> I want to encourage everybody to participate in this public discussion.
>>
>>>
>>> Blink-in-JS is a good thing if it doesn't require any private script API.
>>> We need a good guideline about private script APIs. We need to balance the
>>> following two facts:
>>>
>>> - We should not mess up the platform by adding private script APIs. A
>>> private script API is a bad thing in both philosophy and practice.
>>> - We should move Blink-in-JS work forward with fewer engineering
>>> resources. It is not productive to spend a lot of time in moving
>>> will-be-deprecated features to Blink-in-JS.
>>>
>>> Here is a revised version of the guideline:
>>>
>>> ====================
>>> - If you plan to implement a feature in Blink-in-JS, you need to send an
>>> intent-to-implement to blink-dev@ and get a consensus.
>>
>>
>> With the reasoning above, should this be an intent to deprecate instead?
>>
>>>

>>> - You need to try your best to implement Blink-in-JS without relying on
>>> private script APIs. If you really need to add a private script API, you
>>> need to get an LGTM from one API owner. The private script API must meet

>>> either of the following conditions:
>>>

>>> (a) The private script API is a missing part of the current web and going

>>> to be exposed to the web in the future.
>>
>>

>>> What do you think?
>>>
>>>
>>>
>>>
>>> On Sun, Oct 19, 2014 at 9:04 AM, Elliott Sprehn <esp...@chromium.org>
>>> wrote:t

>>>
>>>> I don't think we should be adding any extra APIs. Down that path leads
>>>> madness and the same messes we're trying to prevent by moving certain
>>>> features into Blink-in-JS. I _do_ think we should move the media controls
>>>> into Blink-in-JS, whatever APIs are missing we should add to the web
>>>> platform. Please send emails to public-webapps so we can make that happen.
>>>>
>>>>

[Kentaro Hara]

Rick: 

There's risk in the other direction too.  When we implement high-level features in C++ with hooks into whatever system reviewers will tolerate, we can deceive ourselves into thinking it's OK with arguments like "frameworks should never need this ability - this code is special".  If we make the bar too high, people will just avoid using blink-in-js and further exacerbate the monolithic nature of our platform and code base. 

 

Instead I hope we can strike a good balance that encourages people to try to build their feature on top of primitives, and incrementally works towards refining those primitives into part of web platform.  That can help advance the platform in ways we might not predict (a "special case" often turns out not to be so special after discussion with people who see related special cases).  I've seen this process be pretty valuable in other traditional platforms (eg. co-evolution of the windows kernel with applications/frameworks).

Agreed.

It is important not to mess up the platform by adding random private script APIs, but it is also important to factor out more second-class citizens (I'd put not only XSLT but also MediaControls, TextTrack, VTT, XMLSerializer, <marquee>, editing/ etc to second-class citizens) from C++ to JavaScript and thus improve hackability of the core code base. Good hackability is a key to make more performance improvement and implement more important features more quickly. (In fact, WebKit already did it for MediaControls and Mozilla already did it for TextTrack and VTT.) We need to think about a good balancing point of them.

My worry about putting a too strict rule to private script APIs is that it will discourage people from using Blink-in-JS and thus prevent the platform from evolving in the way Rick described above. As far as we learned in XSLT-in-JS, <marquee>-in-JS, MediaControls-in-JS etc, it is not easy to notice the need of private script APIs until we fully implement it and hit a weird edge-case behavior of the web. At that point, we notice the need of private script APIs at the first time. If we have to suspend the work until we fully standardize the private script APIs, people won't be willing to spend time in implementing some features in Blink-in-JS.

We shouldn't break the platform by adding random private script APIs. On the other hand, I don't think we should put a too strict rule about it to evolve the platform. I think we need a good guideline and decision-making process to balance the two :)

Mike:

> - For experimenting with or learning about the platform, we should use branches, and not trunk. 

 

Hrm. What's the bar here? My impression is that we've been pretty lax with our intent to implement process; when should something bake on a branch before landing in trunk?

IMHO, finding a missing part of the current platform is not a _direct_ goal of Blink-in-JS. It is a great by-product of Blink-in-JS work that is intending to implement some feature in JavaScript for other direct goals. For example, I don't think we are planning to implement an <audio> tag in Blink-in-JS and add missing APIs as private script APIs to make it workable. (This kind of work would be valuable, but I think it should be done using a branch.)

P.S.,

BTW, please come to the "Future of Blink-in-JS" session at BlinkOn3 if you're interested in this discussion. I'm planning to make the session open for discussions rather than using a lot of slides :-)

[Kentaro Hara]

Thanks Jeremy!

(The following comments are just for clarification. I'm on the same page as Jeremy.)

I think the bar should be lower for APIs which have a small impact on
the platform, like: 

 

- Element.createUserAgentShadowRoot (which is very similar to
createShadowRoot, and exercises a capability we already rely on for
other features), 

 

- UseCounter (which is useful elsewhere in Blink and Chromium, and for
which an alternate implementation could easily be supplied by someone
else), and  

As I mentioned somewhere in this thread, UseCounter is a Blink specific thing and is not a part of the web (specifically, is not a part of IDL files). Thus I think UseCounter is out of the scope of private script APIs. We can add this kind of APIs as utility functions of PrivateScriptRunner just like installClass, DOMException, JSError etc.

 

- callbacks to a C++ class which logically "owns" the Blink-in-JS one
(for instance, someone who wanted to reuse the shadow DOM plugin
placeholder code could map these to whatever behaviour they desired)

I think these callbacks should be a part of the web and thus you shouldn't add private script APIs for them easily. If you cannot write your element using web-exposed event listeners (or something like that), that's a thing you need to consider to expose to the web.

I'm also not sure I understand how Mojo fits into this discussion. I
may be missing context, but it sounds like we're saying "private
bindings are bad, but private Mojo services are good". I'm not sure
what the difference is here, except that one is declared in a .idl
file and the other in a .mojom file, one is located through property
access and the other through navigator.connect, etc.

My take-away is (just) that various people have various goals on Blink-in-JS. I don't think it's a good idea to limit the goals at this point by saying "XXX is a good thing but YYY is a bad thing". Blink is an open platform where various people are contributing, it is more important to have a good guideline to decide go/non-go of each concrete proposal of Blink-in-JS. (That is an intent-to-implement email in my proposed guideline.) It would be easier to discuss go/non-go based on a concrete proposal. So IMHO, I don't think it's constructive to discuss why XXX is good but YYY is bad here. The difference tends to be subjective.