Provide mechanism for autopopulating node.js process.env

src/node/internal/process.ts

@@ -26,63 +26,60 @@ export function nextTick(cb: Function, ...args: unknown[]) {
 // for the worker are accessible from the env argument passed into the fetch
 // handler and have no impact here.
 
-export const env = new Proxy(
-  {},
-  {
-    // Per Node.js rules. process.env values must be coerced to strings.
-    // When defined using defineProperty, the property descriptor must be writable,
-    // configurable, and enumerable using just a falsy check. Getters and setters
-    // are not permitted.
-    set(obj: object, prop: PropertyKey, value: any) {
-      return Reflect.set(obj, prop, `${value}`);
-    },
-    defineProperty(
-      obj: object,
-      prop: PropertyKey,
-      descriptor: PropertyDescriptor
-    ) {
-      validateObject(descriptor, 'descriptor', {});
-      if (Reflect.has(descriptor, 'get') || Reflect.has(descriptor, 'set')) {
-        throw new ERR_INVALID_ARG_VALUE(
-          'descriptor',
-          descriptor,
-          'process.env value must not have getter/setter'
-        );
-      }
-      if (!descriptor.configurable) {
-        throw new ERR_INVALID_ARG_VALUE(
-          'descriptor.configurable',
-          descriptor,
-          'process.env value must be configurable'
-        );
-      }
-      if (!descriptor.enumerable) {
-        throw new ERR_INVALID_ARG_VALUE(
-          'descriptor.enumerable',
-          descriptor,
-          'process.env value must be enumerable'
-        );
-      }
-      if (!descriptor.writable) {
-        throw new ERR_INVALID_ARG_VALUE(
-          'descriptor.writable',
-          descriptor,
-          'process.env value must be writable'
-        );
-      }
-      if (Reflect.has(descriptor, 'value')) {
-        Reflect.set(descriptor, 'value', `${descriptor.value}`);
-      } else {
-        throw new ERR_INVALID_ARG_VALUE(
-          'descriptor.value',
-          descriptor,
-          'process.env value must be specified explicitly'
-        );
-      }
-      return Reflect.defineProperty(obj, prop, descriptor);
-    },
-  }
-);
+export const env = new Proxy(utilImpl.getEnvObject(), {
+  // Per Node.js rules. process.env values must be coerced to strings.
+  // When defined using defineProperty, the property descriptor must be writable,
+  // configurable, and enumerable using just a falsy check. Getters and setters
+  // are not permitted.
+  set(obj: object, prop: PropertyKey, value: any) {
+    return Reflect.set(obj, prop, `${value}`);
+  },
+  defineProperty(
+    obj: object,
+    prop: PropertyKey,
+    descriptor: PropertyDescriptor
+  ) {
+    validateObject(descriptor, 'descriptor', {});
+    if (Reflect.has(descriptor, 'get') || Reflect.has(descriptor, 'set')) {
+      throw new ERR_INVALID_ARG_VALUE(
+        'descriptor',
+        descriptor,
+        'process.env value must not have getter/setter'
+      );
+    }
+    if (!descriptor.configurable) {
+      throw new ERR_INVALID_ARG_VALUE(
+        'descriptor.configurable',
+        descriptor,
+        'process.env value must be configurable'
+      );
+    }
+    if (!descriptor.enumerable) {
+      throw new ERR_INVALID_ARG_VALUE(
+        'descriptor.enumerable',
+        descriptor,
+        'process.env value must be enumerable'
+      );
+    }
+    if (!descriptor.writable) {
+      throw new ERR_INVALID_ARG_VALUE(
+        'descriptor.writable',
+        descriptor,
+        'process.env value must be writable'
+      );
+    }
+    if (Reflect.has(descriptor, 'value')) {
+      Reflect.set(descriptor, 'value', `${descriptor.value}`);
+    } else {
+      throw new ERR_INVALID_ARG_VALUE(
+        'descriptor.value',
+        descriptor,
+        'process.env value must be specified explicitly'
+      );
+    }
+    return Reflect.defineProperty(obj, prop, descriptor);
+  },
+});
 
 export function getBuiltinModule(id: string): any {
   return utilImpl.getBuiltinModule(id);

src/node/internal/util.d.ts

@@ -120,6 +120,7 @@ export function isBoxedPrimitive(
   value: unknown
 ): value is number | string | boolean | bigint | symbol;
 
+export function getEnvObject(): Record<string, string>;
 export function getBuiltinModule(id: string): any;
 export function getCallSite(frames: number): Record<string, string>[];
 export function processExitImpl(code: number): void;

src/workerd/api/node/tests/process-nodejs-test.js

@@ -6,3 +6,23 @@ export const processPlatform = {
     assert.ok(['darwin', 'win32', 'linux'].includes(process.platform));
   },
 };
+
+process.env.BAZ = 1;
+const env = { ...process.env };
+
+export const processEnv = {
+  async test() {
+    assert.strictEqual(env.FOO, 'BAR');
+
+    // It should be possible to mutate the process.env at runtime.
+    assert.strictEqual(env.BAZ, '1');
+
+    // Any binding that is not explicitly a text binding should be
+    // ignored.
+    assert.strictEqual(env.BAR, undefined);
+
+    // Test that imports can see the process.env at the top level
+    const { FOO } = await import('mod');
+    assert.strictEqual(FOO, 'BAR');
+  },
+};

src/workerd/api/node/tests/process-nodejs-test.wd-test

@@ -5,10 +5,18 @@ const unitTests :Workerd.Config = (
     ( name = "nodejs-process-test",
       worker = (
         modules = [
-          (name = "worker", esModule = embed "process-nodejs-test.js")
+          (name = "worker", esModule = embed "process-nodejs-test.js"),
+          (name = "mod", esModule = "export const { FOO } = process.env;")
+        ],
+        compatibilityDate = "2024-12-28",
+        compatibilityFlags = [
+          "nodejs_compat",
+          "nodejs_compat_populate_process_env"
+        ],
+        bindings = [
+          (name = "FOO", text = "BAR"),
+          (name = "BAR", json = "{}"),
         ],
-        compatibilityDate = "2024-10-11",
-        compatibilityFlags = ["nodejs_compat"],
       )
     ),
   ],

src/workerd/api/node/util.c++

@@ -234,6 +234,10 @@ jsg::JsValue UtilModule::getBuiltinModule(jsg::Lock& js, kj::String specifier) {
   return js.undefined();
 }
 
+jsg::JsObject UtilModule::getEnvObject(jsg::Lock& js) {
+  return js.getEnv(true);
+}
+
 namespace {
 [[noreturn]] void handleProcessExit(jsg::Lock& js, int code) {
   // There are a few things happening here. First, we abort the current IoContext

src/workerd/api/node/util.h

@@ -239,6 +239,8 @@ class UtilModule final: public jsg::Object {
     return processPlatform;
   }
 
+  jsg::JsObject getEnvObject(jsg::Lock& js);
+
   JSG_RESOURCE_TYPE(UtilModule) {
     JSG_NESTED_TYPE(MIMEType);
     JSG_NESTED_TYPE(MIMEParams);
@@ -258,6 +260,9 @@ class UtilModule final: public jsg::Object {
     JSG_METHOD(previewEntries);
     JSG_METHOD(getConstructorName);
     JSG_METHOD(getCallSite);
+    // TODO(cleanup): It might be about time to separate some of these out
+    // to a different module.
+    JSG_METHOD(getEnvObject);
 
 #define V(Type) JSG_METHOD(is##Type);
     JS_UTIL_IS_TYPES(V)

src/workerd/io/compatibility-date.capnp

@@ -679,4 +679,10 @@ struct CompatibilityFlags @0x8f8c1b68151b6cef {
       $compatDisableFlag("cache_no_cache_disabled")
       $experimental;
   # Enables the use of cache: no-cache in the fetch api.
+
+  populateProcessEnv @71 :Bool
+      $compatEnableFlag("nodejs_compat_populate_process_env")
+      $compatDisableFlag("nodejs_compat_dot_not_populate_process_env");
+  # Automatically populate process.env from text bindings only
+  # when nodejs_compat is being used.
 }

src/workerd/jsg/jsg.h

@@ -2675,6 +2675,13 @@ class Lock {
   // the inspector (if attached), or to KJ_LOG(Info).
   virtual void reportError(const JsValue& value) = 0;
 
+  // Sets an env value that will be expressed on the process.env
+  // if/when nodejs-compat mode is used.
+  virtual void setEnvField(const JsValue& name, const JsValue& value) = 0;
+
+  // Returns the env base object.
+  virtual JsObject getEnv(bool release = false) = 0;
+
  private:
   // Mark the jsg::Lock as being disallowed from being passed as a parameter into
   // a kj promise coroutine. Note that this only blocks directly passing the Lock

src/workerd/jsg/setup.c++

@@ -423,6 +423,7 @@ void IsolateBase::dropWrappers(kj::FunctionParam<void()> drop) {
     // Make sure v8::Globals are destroyed under lock (but not until later).
     KJ_DEFER(symbolAsyncDispose.Reset());
     KJ_DEFER(opaqueTemplate.Reset());
+    KJ_DEFER(envObj.Reset());
 
     // Make sure the TypeWrapper is destroyed under lock by declaring a new copy of the variable
     // that is destroyed before the lock is released.

src/workerd/jsg/setup.h

@@ -261,6 +261,9 @@ class IsolateBase {
   // object with 2 internal fields.
   v8::Global<v8::FunctionTemplate> opaqueTemplate;
 
+  // Object that is used as the underlying target of process.env when nodejs-compat mode is used.
+  v8::Global<v8::Object> envObj;
+
   // Polyfilled Symbol.asyncDispose.
   v8::Global<v8::Symbol> symbolAsyncDispose;
 
@@ -665,6 +668,24 @@ class Isolate: public IsolateBase {
       }
     }
 
+    // Sets an env value that will be expressed on the process.env
+    // if/when nodejs-compat mode is used.
+    void setEnvField(const JsValue& name, const JsValue& value) override {
+      getEnv().set(*this, name, value);
+    }
+
+    // Returns the env base object.
+    JsObject getEnv(bool release = false) override {
+      KJ_DEFER({
+        if (release) jsgIsolate.envObj.Reset();
+      });
+      if (jsgIsolate.envObj.IsEmpty()) {
+        v8::Local<v8::Object> env = obj();
+        jsgIsolate.envObj.Reset(v8Isolate, env);
+      }
+      return JsObject(jsgIsolate.envObj.Get(v8Isolate));
+    }
+
    private:
     Isolate& jsgIsolate;
 

src/workerd/server/workerd-api.c++

@@ -711,6 +711,9 @@ static v8::Local<v8::Value> createBindingValue(JsgWorkerdIsolate::Lock& lock,
 
     KJ_CASE_ONEOF(text, kj::String) {
       value = lock.wrap(context, kj::mv(text));
+      if (featureFlags.getPopulateProcessEnv() && featureFlags.getNodeJsCompat()) {
+        lock.setEnvField(lock.str(global.name), jsg::JsValue(value));
+      }
     }
 
     KJ_CASE_ONEOF(data, kj::Array<byte>) {