doc: vm, run http server in vm by requiring #5323

eljefedelrodeodeljefe · 2016-02-19T11:38:23Z

As user in order to run node code in a vm, you would need to apply some objects to it. This is not quite well documented and may or may not have been reason for a series of issues and SO questions.

This PR would add an example to explain this. It is to some extent controversial and was discussed in a code PR #4955. Issue would have been nodejs/node-v0.x-archive#9211 and this link to SO.

An easier solution would be to use eval(), which I regard as an anti-pattern.
~~Also it uses require('module').wrap(code), which I believe to be a "private" API.~~ I have taken and modified this example from the referenced issues.

/cc @nodejs/documentation

vkurchatkin · 2016-02-19T11:55:55Z

doc/api/vm.markdown

+console.log('Server running at http://127.0.0.1:8124/');
+`
+
+let wrap = require('module').wrap(code)


module is private

Please make valuable comments that bring the discussion forth not back. Any other way then than this and eval?

vm.runInThisContext(` (function(require) { require('http') }) `)(require)

eljefedelrodeodeljefe · 2016-02-19T12:38:02Z

Force pushed this. Doesn't look pretty but solves the problem.

Knighton910 · 2016-02-19T17:25:53Z

👍 @eljefedelrodeodeljefe

jasnell · 2016-02-19T18:50:25Z

doc/api/vm.markdown

+const vm = require('vm')
+
+let code = `
+(function(require) {


minor nit... having the let code = on a separate line with no indenting on the next line makes it a bit confusing.

agree. fixed and force pushed. Thx.

jasnell · 2016-02-19T18:50:57Z

LGTM

silverwind · 2016-03-03T00:39:53Z

doc/api/vm.markdown

@@ -301,6 +301,34 @@ e.g. `(0,eval)('code')`. However, it also has the following additional options:
 - `timeout`: a number of milliseconds to execute `code` before terminating
  execution. If execution is terminated, an [`Error`][] will be thrown.

+## Example: Run a Server within a VM


I think this should either not be a heading, or a 3rd level heading.

I think we are using the heading style when it is an example, outside of a method, but rather a guide or such. E.g. here https://github.com/nodejs/node/blob/master/doc/api/readline.markdown#example-tiny-cli . If you'd rather want it belonging to .runInThisContext(), I can do it w/o pounds.

Having a look at for example streams, it would be 3rd level, but because it's having 2nd level topics like Writable etc. We are a little inconsistent about this I fear. :(

No strong opinions though.

eljefedelrodeodeljefe · 2016-03-07T23:04:22Z

@jasnell agree. Changed it to what you provided.

Also added this issue, for potential harmonization of pronouns nodejs/docs#87

Qard · 2016-03-07T23:42:02Z

Not sure how I feel about documenting this in this way. Normally the vm functions are meant to provide a sandboxed context and this is doing the opposite. The problem I see here is that it's not immediately clear that require is not just a stateless function. Using require will stuff modules into the cache globally, and you could do some nefarious things, like mess with the contents of require.cache. If we do want to document this, I think we need to be very clear about the risks involved.

As a side note: I'd only really consider eval() to be an anti-pattern when used on user-supplied code. In a controlled environment, I'd consider it at worst to be a possible deoptimization trigger. It's not actually that bad, if you are careful.

eljefedelrodeodeljefe · 2016-03-08T01:33:11Z

I'd wish for the API to be a little less confusing, but it is what is and at least it allows for some configuration. Also I wouldn't use eval() because you can't directly return from it. The use case I found for it is in a child_process - possibly - on a remote system. The layer of security then would be to share explicitly share resources between parent and child or not.

Documenting dangers would be fine of course. Maybe also hinting to the use case above.

jasnell · 2016-03-21T22:59:48Z

@Qard @eljefedelrodeodeljefe ... any further thoughts on this one?

Qard · 2016-03-22T01:00:44Z

It worries me a little, but I think I'm 👍 overall. LGTM.

Might be worth discussing more in a docs meeting, but I think we can add to it later rather than blocking.

MylesBorins · 2016-03-23T22:50:17Z

@eljefedelrodeodeljefe I was just about to land this but noticed the commit message is not so informative. Would you be able to update that? LGTM otherwise

eljefedelrodeodeljefe · 2016-03-30T09:13:28Z

I have updated the commit message to reflect intention. Also I have added @Qard's remarks concerning the statefulness of require in this case in a note-section below the example.

Also happy in case we need broader discussion

jasnell · 2016-04-01T16:29:17Z

LGTM

thefourtheye · 2016-04-02T06:26:52Z

doc/api/vm.markdown

@@ -301,6 +301,38 @@ e.g. `(0,eval)('code')`. However, it also has the following additional options:
 - `timeout`: a number of milliseconds to execute `code` before terminating
  execution. If execution is terminated, an [`Error`][] will be thrown.

+## Example: Run a Server within a VM
+
+The context of `.runInThisContext()` refers to the v8 context. The code passed


Minot nit. I think it is V8.

eljefedelrodeodeljefe · 2016-04-02T19:18:07Z

Addressed latest comments and force pushed. @thefourtheye now with semi-colons, thx.

jasnell · 2016-04-19T00:14:29Z

ping @thefourtheye

@jasnell

From squashed: remove you reference, @jasnell Also: The intention behind is to present the user a way he/she can execute the node code in a vm context. The current API doesn't allow this out-of-the-box, since it is neither passing a require function nor creating context with one. The missing docs for this behaviour have produced a number of Q&A items and have also been discussed in the node-archive repo. In both cases there was no real canonical answer. Proposed API changes, haven't moved forward. ref: nodejs/node-v0.x-archive#9211, #4955

eljefedelrodeodeljefe · 2016-04-21T08:01:49Z

rebased. Also tried to contact @thefourtheye concerning sign-off on slack. But I think he is just incredibly busy.

thefourtheye · 2016-04-21T15:31:41Z

Really sorry about the delay. LGTM.

jasnell · 2016-04-21T16:00:00Z

Awesome, ok, one final ping to @nodejs/documentation as a last call for comments.

benjamingr · 2016-04-21T21:29:30Z

LGTM

Qard · 2016-04-21T22:23:44Z

LGTM

The intention behind is to present the user a way to execute code in a vm context. The current API doesn't allow this out-of-the-box, since it is neither passing a require function nor creating context with one. The missing docs for this behaviour have produced a number of Q&A items and have also been discussed in the node-archive repo. In both cases there was no real canonical answer. Refs: nodejs/node-v0.x-archive#9211, #4955 PR-URL: #5323 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Stephen Belanger <admin@stephenbelanger.com> Reviewed-By: Myles Borins <myles.borins@gmail.com> Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com> Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>

jasnell · 2016-04-22T04:48:28Z

Landed in 6815a3b. Fixed up the commit log a bit

The intention behind is to present the user a way to execute code in a vm context. The current API doesn't allow this out-of-the-box, since it is neither passing a require function nor creating context with one. The missing docs for this behaviour have produced a number of Q&A items and have also been discussed in the node-archive repo. In both cases there was no real canonical answer. Refs: nodejs/node-v0.x-archive#9211, nodejs#4955 PR-URL: nodejs#5323 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Stephen Belanger <admin@stephenbelanger.com> Reviewed-By: Myles Borins <myles.borins@gmail.com> Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com> Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>

The intention behind is to present the user a way to execute code in a vm context. The current API doesn't allow this out-of-the-box, since it is neither passing a require function nor creating context with one. The missing docs for this behaviour have produced a number of Q&A items and have also been discussed in the node-archive repo. In both cases there was no real canonical answer. Refs: nodejs/node-v0.x-archive#9211, #4955 PR-URL: #5323 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Stephen Belanger <admin@stephenbelanger.com> Reviewed-By: Myles Borins <myles.borins@gmail.com> Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com> Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>

MylesBorins · 2016-06-01T23:28:36Z

@jasnell / @eljefedelrodeodeljefe is this something we want for lts?

MylesBorins · 2016-07-01T00:11:03Z

ping @eljefedelrodeodeljefe @jasnell

The intention behind is to present the user a way to execute code in a vm context. The current API doesn't allow this out-of-the-box, since it is neither passing a require function nor creating context with one. The missing docs for this behaviour have produced a number of Q&A items and have also been discussed in the node-archive repo. In both cases there was no real canonical answer. Refs: nodejs/node-v0.x-archive#9211, #4955 PR-URL: #5323 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Stephen Belanger <admin@stephenbelanger.com> Reviewed-By: Myles Borins <myles.borins@gmail.com> Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com> Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>

vkurchatkin reviewed Feb 19, 2016
View reviewed changes

mscdex added doc Issues and PRs related to the documentations. vm Issues and PRs related to the vm subsystem. labels Feb 19, 2016

jasnell reviewed Feb 19, 2016
View reviewed changes

silverwind reviewed Mar 3, 2016
View reviewed changes

thefourtheye reviewed Apr 2, 2016
View reviewed changes

jasnell closed this Apr 22, 2016

MylesBorins added the lts-watch-v4.x label Jun 1, 2016

MylesBorins added land-on-v4.x and removed lts-watch-v4.x labels Jul 11, 2016

MylesBorins mentioned this pull request Jul 12, 2016

v4.5.0 proposal #7688

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

doc: vm, run http server in vm by requiring #5323

doc: vm, run http server in vm by requiring #5323

eljefedelrodeodeljefe commented Feb 19, 2016

vkurchatkin Feb 19, 2016

eljefedelrodeodeljefe Feb 19, 2016

vkurchatkin Feb 19, 2016

eljefedelrodeodeljefe commented Feb 19, 2016

Knighton910 commented Feb 19, 2016

jasnell Feb 19, 2016

eljefedelrodeodeljefe Feb 19, 2016

jasnell commented Feb 19, 2016

silverwind Mar 3, 2016

eljefedelrodeodeljefe Mar 4, 2016

eljefedelrodeodeljefe commented Mar 7, 2016

Qard commented Mar 7, 2016

eljefedelrodeodeljefe commented Mar 8, 2016

jasnell commented Mar 21, 2016

Qard commented Mar 22, 2016

MylesBorins commented Mar 23, 2016

eljefedelrodeodeljefe commented Mar 30, 2016

jasnell commented Apr 1, 2016

thefourtheye Apr 2, 2016

eljefedelrodeodeljefe commented Apr 2, 2016

jasnell commented Apr 19, 2016

eljefedelrodeodeljefe commented Apr 21, 2016

thefourtheye commented Apr 21, 2016

jasnell commented Apr 21, 2016

benjamingr commented Apr 21, 2016

Qard commented Apr 21, 2016

jasnell commented Apr 22, 2016

MylesBorins commented Jun 1, 2016

MylesBorins commented Jul 1, 2016

doc: vm, run http server in vm by requiring #5323

doc: vm, run http server in vm by requiring #5323

Conversation

eljefedelrodeodeljefe commented Feb 19, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

eljefedelrodeodeljefe commented Feb 19, 2016

Knighton910 commented Feb 19, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jasnell commented Feb 19, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

eljefedelrodeodeljefe commented Mar 7, 2016

Qard commented Mar 7, 2016

eljefedelrodeodeljefe commented Mar 8, 2016

jasnell commented Mar 21, 2016

Qard commented Mar 22, 2016

MylesBorins commented Mar 23, 2016

eljefedelrodeodeljefe commented Mar 30, 2016

jasnell commented Apr 1, 2016

Choose a reason for hiding this comment

eljefedelrodeodeljefe commented Apr 2, 2016

jasnell commented Apr 19, 2016

eljefedelrodeodeljefe commented Apr 21, 2016

thefourtheye commented Apr 21, 2016

jasnell commented Apr 21, 2016

benjamingr commented Apr 21, 2016

Qard commented Apr 21, 2016

jasnell commented Apr 22, 2016

MylesBorins commented Jun 1, 2016

MylesBorins commented Jul 1, 2016