Deprecating _third_party_main

[BridgeAR]

I stumbled upon some very old code in the loader with the following code comment:

// To allow people to extend Node in different ways, this hook allows
// one to drop a file lib/_third_party_main.js into the build
// directory which will be executed instead of Node's normal loading.

So instead of the regular loader it is going to load the new file. However, that is only the case if that file is also added to node.gyp. This "feature" has never been documented and seems to be used very rarely when searching for it with google. I am not really sure if the best way to deal with this is to document this or to deprecate it but keeping it as is does not seem to be ideal. Is this something we really want to support officially? This functionality seems rather odd to me.

Ping @nodejs/tsc

[addaleax]

I was talking about this with @rubys at JSI – They were looking into splitting the bootstrap function into two parts as a better way for addressing the embedder use case here (the parts are a) basically everything that happens before _third_party_main, i.e. setup code and b) everything after it, i.e. starting userland scripts).

If embedders are given the option of only executing bootstrap code up to the point where we’d currently call _third_party_main, and make the rest optional, they should be able to achieve the same things in a cleaner fashion.

[rubys]

@addaleax I agree. Giving people a better alternative then deprecating _third_party_main is the way to go.

[rubys]

See #23265

[Trott]

Since it's undocumented and is a compile-time/build option, I don't think the doc-deprecation and runtime-deprecations are applicable. I think we can go right to a semver-major removal, if that's what we wish to do. I guess that should wait for the alternative approach proposed by @rubys and @addaleax? Is that something that is in the "oh yeah, we're totally implementing it" phase? Or more of the "we kicked this idea around and kinda like it, but that's as far as we got" phase?

[bnoordhuis]

This issue saw its anniversary last Friday. Should it remain open?

[addaleax]

I would keep it open for a bit, I’ve started doing some more work towards a proper embedder API and maybe something will come out of that in terms of a better solution than this for embedders.

[jasnell]

Ping @addaleax ... where are we at in terms of moving forward on this?

[addaleax]

@jasnell Given that an alternative exists now, I think we could move forward here, but it’s a bit tricky:

• A JS deprecation warning is useless here, it’s effectively equivalent to fully breaking this feature.
• A C++ deprecation warning is not available for this.

Ultimately, I think the closest thing we have to this is the existing deprecation of LoadEnvironment(env) since v14.1.0. Users of _third_party_main are most likely to use that entry point, so I think the only thing we can do is consider _third_party_main already deprecated, and remove it in v15.0.0 or v16.0.0.

I’ll open a PR for removal and we’ll see how that goes.

[jasnell]

That works, I think.

[addaleax]

Removal PR → #33971

[ledbit]

@addaleax what's the alternative to _third_party_main.js ?

[addaleax]

@ledbit https://nodejs.org/api/embedding.html

[ledbit]

@addaleax - thanks for the quick reply! I was just to about to update the comment with the link - as the author of js2bin I'm trying to figure out how to integrate with the new API without having to deal with patching the .gyp files at build time. I'd imaging @calebboyd author of nexe will be running into a similar issue when moving to Node 15.x

[addaleax]

@ledbit Yeah, I admit that that’s a bit tricky, I ran into this with boxednode as well and I’m not super happy about having to patch the gyp files (although there I do that mostly for addon support).

Tbh, I think the real solution here would be for Node.js to publish usable static library files as part of its release process alongside the executable binaries for the different platforms.

[ledbit]

@addaleax I was taking a look at the node init sequence and at first pass it seems like there are quite a few things which would need to be duplicated and kept in sync - e.g. the use of NODE_EXTRA_CA_CERTS as part of InitializeOncePerProcess

main
 node::Start
   InitializeOncePerProcess

There are also quite a few other signal handling / debugging tracing - e.g. the lack of calling node::PlatformInit.

boxednode looks very interesting, I'll research that more in the AM

[calebboyd]

+100 for a static library @addaleax 😂
For nexe I'm planning to migrate to the embedding api on 14+ -- But the use cases are pretty broad right now so I've not had bandwidth to figure out what the approach needs to be.

[ledbit]

@addaleax and @calebboyd maybe I'm missing something obvious here, but how exactly would a static library help? Also, the new embedding API seems quite a bit more cumbersome and prone to maintenance overhead as Node's startup sequence evolves - e.g there's quite a bit of code in boxednode that is lifted from node.cc (albeit with a note to expose an API on the node side - pointing to more work to be done on both node and boxednode side)

My $0.02: the _third_party_main.js approach was a very elegant solution for someone who wanted to simply embed their .js application into Node at compile time. Why can't the two methods co-exist?

[joyeecheung]

I think @ledbit's issue comes down to "how can we tell Node.js to embed a JS starting point during the building process without having to patch node.gyp". I wonder though why haven't we ever tried implementing this with a configure option? Like ./configure --main-script /path/to/script which can work with a condition in node.gyp to embed the source into the code with a file name that Node.js can identify as default starting point.

[ledbit]

@joyeecheung - exactly! With the _third_party_main.js in js2bin I'm using --link-module approach to avoid having to modify node.gyp as well as avoid patching any other files. I've been trying to understand the benefits of removing support for _third_party_main.js but failing ... @BridgeAR or @addaleax can you please add some info on what was broken with that approach? (other than not doced?)