Adds Mojo IDL.

third_party/WebKit/Source/core/mojo/Mojo.idl

Index: third_party/WebKit/Source/core/mojo/Mojo.idl
diff --git a/third_party/WebKit/Source/core/mojo/Mojo.idl b/third_party/WebKit/Source/core/mojo/Mojo.idl
new file mode 100644
index 0000000000000000000000000000000000000000..fcca210443e70d56087bdf6583e9c566d449b362
--- /dev/null
+++ b/third_party/WebKit/Source/core/mojo/Mojo.idl
@@ -0,0 +1,48 @@
+// Copyright 2016 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+typedef unsigned long MojoResult;
+typedef unsigned long MojoHandleSignals;
+typedef unsigned long MojoCreateMessagePipeOptionsFlags;
+typedef unsigned long MojoWriteMessageFlags;
+typedef unsigned long MojoReadMessageFlags;
+
+callback MojoWatchCallback = void (MojoResult result);
+
+interface Mojo {

[jbroman, 2016/12/20 23:21:57]

Should all of these interfaces have [NoInterfaceObject] to avoid their
interfaces being installed on the global object? If I understand correctly, they
will get access to it by being given an instance of Mojo (and can reach
constants from there).

[alokp, 2017/01/09 23:33:09]

We do need to install MojoHandle interface so that we can do "handle instanceOf
MojoHandle". I agree that this particular interface can have NoInterfaceObject,
but we may still want to install it for consistency and not have to pass the
instance around just to access the constants?

Anyways, I did use NoInterfaceObject in the initial versions of the patch.
esprehn@ asked me to remove those. Elliot?

[jbroman, 2017/01/10 20:46:30]

1. My main concern here is that I do not want all Blink script contexts to have
the Mojo family of objects exposed, which is what will happen at present (you
probably have a test failure in
virtual/stable/webexposed/global-interface-listing.html at present).
2. My secondary concern is that in those contexts where we do intend to use it,
it's not clear to me whether we want the Mojo stuff visible on the global (lest
cast receiver apps be tempted to issue their own Mojo calls).

Possibly we could address (1) by applying the infrastructure built for origin
trials to conditionally expose this.

[alokp, 2017/01/11 21:53:01]

Is this concern about cluttering the context with unnecessary interfaces or
something else? We are not unconditionally injecting a Mojo instance into every
context.
Cast Apps will not consume the mojo APIs directly. They will use Cast SDK, which
in turn will internally use Mojo. Pardon my ignorance - I am not sure what you
mean by this comment. Can you elaborate?
Can you point me to this infrastructure? I am happy to use it if that is the
recommended approach.

[jbroman, 2017/01/11 23:00:00]

Right, I don't want the interface to be visible in contexts where we don't
intend to inject a Mojo object. If NoInterfaceObject is not specified, then by
default each interface has a function added to the global object, which is
visible to script. (e.g. in this case, it would be "window.Mojo"). I do not want
this, or any of the others, to be visible to the open web.
I guess I'm worried that some cast developer will spot the Mojo things on the
global, and be tempted to use it to send their own messages (e.g. if there's
something possible via the Mojo service but not exposed through the Cast SDK).
The harder we make it, the more obvious it will be to the author that they
should not be doing this. I'm not familiar enough with our relationship with
these developers, but I know that on the Web and on Android developers love to
use "private" APIs.

Something like this might be possible:

var savedCreateMessagePipe = Mojo.prototype.createMessagePipe;
Mojo.prototype.createMessagePipe = function(...args) {
  window.secretMojoObject = this;
  return savedCreateMessagePipe.call(this, args);
};
// after cast SDK creates at least one message pipe, author script has gained
access to the |mojo| object

If the interface objects aren't exposed, it becomes harder (though still not
necessarily impossible) to get a handle on these objects.
[cc iclelland]
I think the OriginTrialEnabled= IDL attribute is the start of how it works for
origin trials. Ian would know how this infrastructure works generally, and if
what the current best way to conditionally expose something from WebIDL to JS
contexts.

[alokp, 2017/01/12 01:20:26]

OK - Agreed.
This has not been a problem so far. But agreed that hiding as much as possible
is better. 
OK. Looking into OriginTrialEnabled...

[jbroman, 2017/01/12 02:21:10]

OK, it sounds like esprehn sees this as a "real API" that need not be hidden. In
that case,
you don't need [NoInterfaceObject], but you do need to ensure that we don't
expose the
interface object in contexts except cast receiver apps.
To expand on my comment earlier, origin trials and feature policy are both paths
that
can conditionally enable/disable features at runtime, per document. See, e.g.,
ConditionalFeatures.cpp and ConditionalFeaturesForModules.cpp.

iclelland@ would know what the status of the conditional feature code is, and
how we
can use it here. (Previously we had RuntimeEnabled=, but it was a per-process
setting,
whereas now we can have per-frame granularity.)

[alokp, 2017/01/13 01:07:55]

Not sure if it makes any difference. But we also need to enable mojo-js bindings
for layout tests, webui, and headless. See MojoBindingsType:
https://cs.chromium.org/chromium/src/content/renderer/mojo_bindings_controlle...

Anyways I added origin trials but I am still missing things since I do not know
how to enable the bindings for layout tests for example.

+    const MojoResult RESULT_OK = 0;
+    const MojoResult RESULT_CANCELLED = 1;
+    const MojoResult RESULT_UNKNOWN = 2;
+    const MojoResult RESULT_INVALID_ARGUMENT = 3;
+    const MojoResult RESULT_DEADLINE_EXCEEDED = 4;
+    const MojoResult RESULT_NOT_FOUND = 5;
+    const MojoResult RESULT_ALREADY_EXISTS = 6;
+    const MojoResult RESULT_PERMISSION_DENIED = 7;
+    const MojoResult RESULT_RESOURCE_EXHAUSTED = 8;
+    const MojoResult RESULT_FAILED_PRECONDITION = 9;
+    const MojoResult RESULT_ABORTED = 10;
+    const MojoResult RESULT_OUT_OF_RANGE = 11;
+    const MojoResult RESULT_UNIMPLEMENTED = 12;
+    const MojoResult RESULT_INTERNAL = 13;
+    const MojoResult RESULT_UNAVAILABLE = 14;
+    const MojoResult RESULT_DATA_LOSS = 15;
+    const MojoResult RESULT_BUSY = 16;
+    const MojoResult RESULT_SHOULD_WAIT = 17;
+
+    const MojoHandleSignals HANDLE_SIGNAL_NONE = 0;
+    const MojoHandleSignals HANDLE_SIGNAL_READABLE = 1;
+    const MojoHandleSignals HANDLE_SIGNAL_WRITABLE = 2;
+    const MojoHandleSignals HANDLE_SIGNAL_PEER_CLOSED = 4;
+
+    const MojoCreateMessagePipeOptionsFlags CREATE_MESSAGE_PIPE_OPTIONS_FLAG_NONE = 0;
+    const MojoWriteMessageFlags WRITE_MESSAGE_FLAG_NONE = 0;
+    const MojoReadMessageFlags READ_MESSAGE_FLAG_NONE = 0;
+    const MojoReadMessageFlags READ_MESSAGE_FLAG_MAY_DISCARD = 1;
+
+    [CallWith=ScriptState] MojoWatcher watch(MojoHandle handle, MojoHandleSignals signals, MojoWatchCallback callback);

[jbroman, 2016/12/21 18:09:48]

Most of these look like they could be interface methods on MojoHandle. Is it an
intentional choice not to do that?

handle.watch(signals, function() { ... });

seems a little more idiomatic than

mojo.watch(handle, signals, function() { ... });

Also, how stable will we be making this API? If it needs to be stable because it
interacts with code not shipped with Chromium, we might want to consider some of
the usual web API lessons. For example, might this (or other) functions need
more arguments in the future? If so, we might want to have a dictionary argument
right now.

If that's the case, then this will also lock in the MojoResult constants etc.

[alokp, 2017/01/09 23:33:09]

Good idea. Moved watch, read/writeMessage to MojoHandle. Also created dictionary
arguments.

+
+    MojoCreateMessagePipeResult createMessagePipe(MojoCreateMessagePipeOptions options);
+    MojoResult writeMessage(MojoHandle pipe, BufferSource buffer, sequence<MojoHandle> handles, MojoWriteMessageFlags flags);

[jbroman, 2016/12/21 18:09:48]

We can probably reduce type confusion by making a derived interface for
MojoMessagePipeHandle (like the C++ library does), and having the method take
that instead of MojoHandle. If there are cases where we'll have some MojoHandle
of unknown type and need to expose it to script, then maybe it's not worth the
hassle.

[alokp, 2017/01/09 23:33:09]

Type of MojoHandle is not available when reading a message at the core layer
(Note that MojoReadMessage only provides an array of raw handles). Type becomes
available only after message deserialization at which point C++ library simply
wraps the raw handle into a MojoMessagePipeHandle.

With my limited JS foo, I could not figure out how to convert a JS MojoHandle
type into MojoMessagePipeHandle. I agree that it would be much nicer if we could
do this.

[jbroman, 2017/01/10 20:46:30]

interface MojoMessagePipeHandle : MojoHandle {};

Ideally you'd be able to do things like:
var someHandle = result.handles[0];
console.log(someHandle instanceof MojoMessagePipeHandle); // true

But if we can't tell when we wrap a handle what the right wrapper type for it is
(e.g. when handles are received from a pipe). Blink objects normally know what
their type is when they create their wrappers, but if that's not the case here
then we'd need to add the equivalent of an unsafe cast, which IMHO is worse than
just having it validated after being passed to an API call.

[alokp, 2017/01/11 21:53:01]

We do not know the type of handle when they are read from a pipe, so I guess we
have to live with a single MojoHandle type. MOJO_RESULT_INVALID_ARGUMENT will be
returned if read/writeMessage is called on the handle of wrong type.

+    MojoReadMessageResult readMessage(MojoHandle pipe, MojoReadMessageFlags flags);
+};