@endo/env-options

Parameterizing Modules with Environment Options

JavaScript module semantics resist attempts to parameterize a module's initialization behavior. A module initializes in order according to the path by which it is first imported, and then the initialized module is reused by all the other times it is imported. Compartments give us the opportunity to bind the same import name to different imported modules, depending on the package/compartment doing the import. Compartments also address the difficulty of parameterizing a module's initialization logic, but not in a pleasant manner.

A pleasant parameterization would be for a static module to be function-like with explicit parameters, and for the parameterization to be like calling the static module with parameters in order to derive from it a module instance. Compartments instead lets us parameterize the meaning of a module instance derived from a static module according to the three namespaces provided by the JavaScript semantics, affecting the meaning of a module instance.

• The global variable namespaces.
  • The global scope, aliased to properties of the global object. This is necessarily compartment-wide. In our recommened usage pattern of one compartment per package, each global would be package-wide. (See LavaMoat)
  • The global lexical scope. The SES-shim compartments support these both compartment-wide as well as per-module. But it is not yet clear what we will propose in the Compartment proposal.
• The import namespace.
• The host hooks.

This @endo/env-options package follows the Node precedent for finding Unix environment variable settings: looking for a global process object holding an env object, optionally holding a property with the same name as the option, whose value is the configuration setting of that option.

import { getEnvironmentOption } from '@endo/env-options';
const FooBarOption = getEnvironmentOption('FOO_BAR', 'absent');

The first argument to getEnvironmentOption is the name of the option. The value of FooBarOption would then be the value of globalThis.process.env.FOO_BAR, if present. If value is either absent or undefined, the second argument, such as 'absent', would be used instead.

In either case, reflecting Unix environment variable expectations, the resulting setting must be a string. This restriction also helps ensure that this channel is used only to pass data, not authority beyond the ability to read this global state.

const ENABLED =
  getEnvironmentOption('TRACK_TURNS', 'disabled', ['enabled']) === 'enabled';

getEnvironmentOption also takes an optional third argument, which if present is an exhaustive list of allowed strings other than the default. If present and the actual environment option is neither the default nor one of these allowed strings, then an error is thrown explaining the problem.

const DEBUG_VALUES = getEnvironmentOptionsList('DEBUG');
const DEBUG_AGORIC = environmentOptionsListHas('DEBUG', 'agoric');

Another common convention is for the value of an option to be a comma (',') separated list of strings. getEnvironmentOptionsList will return this list, or an empty list if the option is absent. environmentOptionsListHas will test if this list contains a specific value, or return false if the option is absent.

(Compat note: https://github.com/Agoric/agoric-sdk/issues/8096 explains that for DEBUG specifically, some existing uses split on colon (':') rather than comma. Once these are fixed, then these uses can be switched to use getEnvironmentOptionsList or environmentOptionsListHas.)

Tracking used option names

The '@endo/env-options' module also exports a lower-level makeEnvironmentCaptor that you can apply to whatever object you wish to treat as a global(having a "process" property with its own "env" record), such as the global of another compartment. It returns an entagled pair of a getEnvironmentOption function as above, and a getCapturedEnvironmentOptionNames function that returns an array of the option names used by that getEnvironmentOption function. This is useful to give feedback about which environment variables were actually read, for diagnostic purposes. For example, the ses-shim lockdown once contained code such as the following, to explain which environment variables were read to provide lockdown settings.

import { makeEnvironmentCaptor } from '@endo/env-options';
const {
  getEnvironmentOption,
  getEnvironmentOptionsList,
  environmentOptionsListHas,
  getCapturedEnvironmentOptionNames,
} = makeEnvironmentCaptor(globalThis);
...
const capturedEnvironmentOptionNames = getCapturedEnvironmentOptionNames();
if (capturedEnvironmentOptionNames.length > 0) {
  console.warn(
    `SES Lockdown using options from environment variables ${enJoin(
      arrayMap(capturedEnvironmentOptionNames, q),
      'and',
    )}`,
  );
}

Note of test migration

To reduce cyclic dependencies, the tests of this module have been moved to @endo/ses-ava. Doing yarn test here currently does nothing.