refactor(ses): getenv detects more errors

[erights]

Closes: #XXXX
Refs: #1710

Description

#1710 enhanced getEnvironmentOption with an optional third argument listing all the other allowed choices aside from the default choice. Previously, we had only manual code to detect and complain of unrecognized environment option values. #1710 provides a more declarative form, and reuses the checking-and-complaining logic. However, following #1710 we did not retire much of the previous ad-hoc manual code, nor did we make enough use of this declarative alternative. This PR fixes that.

Security Considerations

An advantage to the old ad-hoc manual style is that the enumeration of all possible alternatives was textually close to the dispatch on the alternative. This makes it easy to keep the two in sync. Thus, a comparative disadvantage of this PR is their separation, leading to maintenance hazards if one is updated but not the other. For example, if the declarative form adds another option that the dispatch code does not take into account, that other option might fall into the dispatch's fall-through case. This may or may not be good, depending on whether the fall through case is carefully chosen to also be appropriate for new not-previously-recognized options.

Scaling Considerations

none

Documentation Considerations

none

Testing Considerations

The text of the error messages for unrecognized options will likely be different. But aside from that there should be no observable difference. Since we do not consider a change to the text of an error message a correctness concern, we consider this PR to effectively be a pure refactor.

Compatibility and Upgrade Considerations

Both before and after this PR, we generally reject unrecognized environment options settings. This makes it difficult to grow existing options with new settings that are ignored if seen by previous code. This hinders plausible development patterns. This PR by itself does not change that. But by centralizing the detect-and-complaint logic and making it more declarative, perhaps we become better set up to address this issue later.

[gibson042]

Rather than manually typing the options, another possibility is updating getEnvironmentOption to do it, albeit at the cost of casting its third argument to @type {const}, as visible by hovering over bindings in the final region of this demonstration.

An advantage to the old ad-hoc manual style is that the enumeration of all possible alternatives was textually close to the dispatch on the alternative. This makes it easy to keep the two in sync. Thus, a comparative disadvantage of this PR is their separation, leading to maintenance hazards if one is updated but not the other.

I think typing can address this too, as also included in the above demonstration.

/** @typedef {(typeof overrideTamingOptions)[number]} OverrideTaming */
const overrideTamingOptions = /** @type {const} */ (['moderate', 'min', 'severe']);
…
const overrideTaming = getenv('LOCKDOWN_OVERRIDE_TAMING', 'moderate', overrideTamingOptions);
…
/**
 * @param {OverrideTaming} overrideTaming
 */
function useOverrideTaming(overrideTaming) {
  if (!['moderate', 'min', 'severe'].includes(overrideTaming)) throw Error();
}

[gibson042]

Suggested change

	errorTaming = getenv('LOCKDOWN_ERROR_TAMING', 'safe', [
	'unsafe',
	'unsafe-debug',
	]),
	errorTaming = /** @type {'safe' | 'unsafe' | 'unsafe-debug'} */ (
	getenv('LOCKDOWN_ERROR_TAMING', 'safe', ['unsafe', 'unsafe-debug'])
	),

[erights]

Hi @gibson042 , I like the idea, but I'd like to do it while avoiding redundancy with types.d.ts. For this example

errorTaming?: 'safe' | 'unsafe' | 'unsafe-debug';

What's the best way for me to do both?

[gibson042]

The way to avoid repetition within TypeScript is by referencing the types of types.d.ts:

Suggested change

	errorTaming = getenv('LOCKDOWN_ERROR_TAMING', 'safe', [
	'unsafe',
	'unsafe-debug',
	]),
	errorTaming = /** @type {Required<LockdownOptions>['errorTaming']} */ (
	getenv('LOCKDOWN_ERROR_TAMING', 'safe', ['unsafe', 'unsafe-debug'])
	),

But note that you won't get full type benefits unless the points of consumption are also updated, e.g. packages/ses/src/error/tame-error-constructor.js

@@ -31,6 +31,11 @@ const tamedMethods = {
 };
 let initialGetStackString = tamedMethods.getStackString;
 
+/** @import {LockdownOptions} from '../../types.js' */
+/**
+ * @param {LockdownOptions['errorTaming']} [errorTaming]
+ * @param {LockdownOptions['stackFiltering']} [stackFiltering]
+ */
 export default function tameErrorConstructor(
   errorTaming = 'safe',
   stackFiltering = 'concise',

However, since these values have runtime effects, they must necessarily be defined in JavaScript. So the least repetitive approach would be to reflect that definition into TypeScript as suggested at #2690 (review), e.g.

/** @typedef {(typeof errorTamingOptions)[number]} ErrorTaming */
const errorTamingOptions = /** @type {const} */ (
  ['safe', 'unsafe', 'unsafe-debug']
);

[gibson042]

Suggested change

	regExpTaming = getenv('LOCKDOWN_REGEXP_TAMING', 'safe', ['unsafe']),
	localeTaming = getenv('LOCKDOWN_LOCALE_TAMING', 'safe', ['unsafe']),
	regExpTaming = /** @type {'safe' | 'unsafe'} */ (
	getenv('LOCKDOWN_REGEXP_TAMING', 'safe', ['unsafe'])
	),
	localeTaming = /** @type {'safe' | 'unsafe'} */ (
	getenv('LOCKDOWN_LOCALE_TAMING', 'safe', ['unsafe'])
	),

[gibson042]

Suggested change

	stackFiltering = getenv('LOCKDOWN_STACK_FILTERING', 'concise', ['verbose']),
	domainTaming = getenv('LOCKDOWN_DOMAIN_TAMING', 'safe', ['unsafe']),
	evalTaming = getenv('LOCKDOWN_EVAL_TAMING', 'safeEval', [
	'unsafeEval',
	'noEval',
	]),
	overrideDebug = arrayFilter(
	stackFiltering = /** @type {'concise' | 'verbose'} */ (
	getenv('LOCKDOWN_STACK_FILTERING', 'concise', ['verbose'])
	),
	domainTaming = /** @type {'unsafe' | 'safe'} */ (
	getenv('LOCKDOWN_DOMAIN_TAMING', 'safe', ['unsafe'])
	),
	evalTaming = /** @type {'safeEval' | 'unsafeEval' | 'noEval'} */ (
	getenv('LOCKDOWN_EVAL_TAMING', 'safeEval', [
	'unsafeEval',
	'noEval',
	])
	),
	/** @type {string[]} */
	overrideDebug = arrayFilter(

[gibson042]

Suggested change

	legacyRegeneratorRuntimeTaming = getenv(
	'LOCKDOWN_LEGACY_REGENERATOR_RUNTIME_TAMING',
	'safe',
	['unsafe-ignore'],
	),
	legacyRegeneratorRuntimeTaming = /** @type {'safe' | 'unsafe-ignore'} */ (
	getenv(
	'LOCKDOWN_LEGACY_REGENERATOR_RUNTIME_TAMING',
	'safe',
	['unsafe-ignore'],
	)
	),

[gibson042]

Suggested change

	__hardenTaming__ = getenv('LOCKDOWN_HARDEN_TAMING', 'safe', ['unsafe']),
	__hardenTaming__ = /** @type {'safe' | 'unsafe'} */ (
	getenv('LOCKDOWN_HARDEN_TAMING', 'safe', ['unsafe'])
	),