on working with proposals from the API WG

[trevnorris]

There is an official API WG which has been charged with creating the "standard" for API compliance. While there's no expectation that the API will never change, achieving minimal change would be optimal. For this and other reasons a more simplified API would be better. Any differing APIs are being created in a backwards compatible way. A goal is that the current core API can be re-implemented using this, and the current API will continue to be the default.

The main blocker for the API WG is to know whether any API decisions would be accepted into core. Can the API WG expect support on this?

/cc @nodejs/tsc

EDIT: Here is the summary of deliverables requested in the latest TSC meeting:

The requested final result is that the VM, and the native code attached to the VM such as libuv, can be replaced. While still allowing compatibility with the existing node ecosystem.

On the native side it has been proposed that a minimal abstraction be used at the module interface to allow API and ABI compatibility across different versions of node. nan has been an excellent project to show the way, but it is both still tightly coupled with V8 and offers no ABI compatibility. Further discussion on this has happened in nodejs/nan#349

On the JS side there has been discussion on creating a lower-level API. This type of interface offers several advantages. Such as, more direct to test, less overhead, easier to adapt to new interfaces. The idea is that current JS node libraries would use this interface, and so anyone that implements it could simply use the same code. It would be similar to the current bindings interface, but with a few alterations to make it more easily adaptable.

Both of these would allow a reliable and testable way for the underpinning of node to be replaced while still offering full support.

[mikeal]

Do you mean the C++ API, the JS API, or both?

It was my understanding that the native addons WG was scoped in such a way to tackle "node.c" in addition to nan.

[trevnorris]

@mikeal This is specifically for the JS API. A few of the reasons for this include:

• Companies wish to create their own JS runtimes that are "officially node compatible".
• An API that experiences less change.
• More explicit inputs/outputs that allow a more comprehensive test suit for compatibility testing.
• Minimal overhead API that more easily allows alternative interfaces to be created.

The native API abstraction is a different discussion. Some of that has been happening on nodejs/nan#349 .

[Fishrock123]

There is an official API WG

Where can it be found? I didn't see a repo or team yet.

Edit:

The main blocker for the API WG is to know whether any API decisions would be accepted into core. Can the API WG expect support on this?

See above, at this point, I'm not entirely sure.

[trevnorris]

Thus far all discussions has been over email. It started a while back, possibly before io.js was around. Though you're right, no repo was created. I'll get back to you on that.

The group was going to tackle both the native and JS APIs, but this issue is specifically for the later.

[Fishrock123]

It's hard to know if we should support something that doesn't fully exist yet. :)

I'd like to be involved though, but I'm not sure I really want to bail out more time for another set of meetings. I feel like this sort of WG should essentially be core?

[trevnorris]

I agree on not wanting more meetings. It should be possible to do most of the work in discussions, emails, etc. Trying to explain APIs is more difficult than just showing a few lines of code anyway.

The origination of this group is from companies that want to provide alternative VMs under the hood, and be "node compatible". While I welcome everyone that wants to be involved, the core team's time is probably better spent by only a few of us working in this group and then bringing results to everyone once they're ready. And company representatives to discuss what they are looking for will definitely be part of the group.

[Fishrock123]

Going to take this off tsc-agenda after today's meeting until this has spun up. :)

[orangemocha]

@trevnorris: @geoffkizer and @jianchun from Chakra make good candidates for participation, and I would like to participate as well.

[trevnorris]

I've updated the OP with the requested information from the TSC meeting.

/cc @domenic

[obastemur]

@trevnorris looking forward to participate in this workgroup.

[domenic]

This looks pretty good. To clarify a bit, what are the actual deliverables? I.e., when can this group's work be considered "finished"? (With ongoing maintenance of course.)

I am guessing based on the OP that would be:

1. A set of C or C++ function signatures that can serve as a facade over JS engine APIs, plus detailed specifications on how they must work, possibly with tests.
   • Then, various parties could implement different versions of these functions which, as long as they conformed to the spec/tests, would allow swapping in their own JS VM.
2. A set of JS function and class signatures that provide all the "low-level" functionality required, with detailed specifications on how they must work, as well as a good set of tests. This set of signatures will likely be similar to the set that can be accessed via process.binding today (including e.g. any special classes used as return types).
   • Then, various parties could implement different versions of these functions and classes, which, as long as they conformed to the spec/tests, would allow swapping in some other libraries instead of libuv/openssl/c-ares/http-parser/etc.

Is that correct? Maybe there is a third deliverable, which is the actual work of creating a V8 implementation of (1) and adapting the current process.binding values to conform to (2)?

[trevnorris]

@domenic Nice overview. The tests are very important. They'll serve as the standard of whether something conforms.

On the third deliverable, don't fully understand (1) and I did forget about (2). The current JS API should end up being reimplemented using the new low level implementation. So basically anyone could pull the code from lib/ and use that directly. Making it much easier to follow the most up to date API.

And something I think you'd be interested in is that other new interfaces, e.g. what's discussed on NG, could begin to be implemented more easily. Though that's just a byproduct of what we're working on. Not a goal we'd have.

[domenic]

On the third deliverable, don't fully understand (1)

I meant, in addition to producing a spec/tests for the JS engine abstraction APIs, you probably also want to create an implementation for those APIs that uses V8, and then port all uses of the V8 API inside io.js's C++ code to be using those engine-agnostic APIs.

[trevnorris]

I don't see the advantage of replacing all instances of the abstracted API within the core code itself. There'd be a single header with the API and internally we'd have the abstraction implementation.

[jasnell]

It's great to see this spinning up. I definitely support this but agree
with not wanting yet another meeting. Let's see what we can accomplish
asynchronously via email and git.
On Jun 16, 2015 1:34 PM, "Trevor Norris" [email protected] wrote:

There is an official API WG which has been charged with creating the
"standard" for API compliance. While there's no expectation that the API
will never change, achieving minimal change would be optimal. For this and
other reasons a more simplified API would be better. Any differing APIs are
being created in a backwards compatible way. A goal is that the current
core API can be re-implemented using this, and the current API will
continue to be the default.

The main blocker for the API WG is to know whether any API decisions would
be accepted into core. Can the API WG expect support on this?

/cc @nodejs/tsc https://github.com/orgs/nodejs/teams/tsc

—
Reply to this email directly or view it on GitHub
#1993.

[trevnorris]

Two questions that weren't completely verified:

• Will the native API discussion happen in a different group than the JS API discussion?
• If so, will native go under the module working group and the JS have its own?

I'd like to get the repo created and start getting everyone involved if possible.

[rvagg]

@trevnorris kick it off and make it happen, _if you build it they will come_ (Disclaimer: usually not true)

• repo: https://github.com/nodejs/api - needs a readme and PR in any working docs or code you have to start discussion I suppose!
• team: https://github.com/orgs/nodejs/teams/api add in anyone who has the capacity to constructively contribute here and wants to be involved

Also /cc @nodejs/addon-api because this is overlapish, if anyone wants in on this discussion raise your hands and you can be added.

[trevnorris]

@rvagg Since the native API discussion has migrated to being about only user facing, should that part move on to the addon WG?

[rvagg]

@trevnorris I think the discussion has strayed from where it should have been and a separate group for internal API discussions would be appropriate and the addons API can piggyback that if/when it evolves to something useful. But, we're trying to schedule a meeting for the addons API group so we could try and come to an agreement about where the borders are during that discussion, since we'll have folks from Microsoft and IBM that are doing API-level stuff in there it should be constructive.

[obastemur]

@rvagg raising both hands.

BTW I'm also confused that wasn't this WG going to work on public API ?

[trevnorris]

@obastemur I'll assume by "this WG" you mean the API WG. Yes, currently all efforts are focused on public API. There was a lengthy discussion on how to abstract away V8 from node internals, but it became apparent that doing so would be too complicated. By instead supplying a solid user facing API vendors can replace everything else under the hood.

[obastemur]

@trevnorris thanks for the clarification. Sounds good

[Fishrock123]

Deferring to https://github.com/nodejs/api