Skip to content

feat(env-options): env-options conveniences for common cases#1710

Merged
erights merged 2 commits intomasterfrom
markm-options-harmony
Jan 10, 2024
Merged

feat(env-options): env-options conveniences for common cases#1710
erights merged 2 commits intomasterfrom
markm-options-harmony

Conversation

@erights
Copy link
Copy Markdown
Contributor

@erights erights commented Aug 2, 2023

refs: Agoric/agoric-sdk#8136
refs: Agoric/agoric-sdk#8096
refs: https://github.com/Agoric/agoric-sdk/blob/master/docs/env.md#DEBUG
refs: #1922

The indirection of getEnvironmentCaptor is only needed to support getCapturedEnvironmentOptionNames
getCapturedEnvironmentOptionNames is not currently used in either endo or agoric-sdk. Thus, we have enhanced
@endo/env/options to also directly export non-capturing forms of the other functions, like getEnvironmentOption, that are made and returned by getEnvironmentCaptor.

The value of an option is often supposed to be a list of strings separated by commas (','). However
Agoric/agoric-sdk#8096 explains that sometimes our code (both in endo and in agoric-sdk) accidentally split on colon (':') instead due to confusion about what the convention was supposed to be.

So that this PR would only be a compat feat PR, this PR does not fix any of those legacy manual uses that got the convention wrong. (Though it does add a TODO that links to Agoric/agoric-sdk#8096.) Rather,
this PR does provide additional conveniences, getEnvironmentOptionsList and environmentOptionsListHas based on the correct comma option.

Later PRs (#1922) that do take the compat hit of switching to comma should also switch to using these new conveniences.

@erights erights self-assigned this Aug 2, 2023
@erights erights force-pushed the markm-options-harmony branch from dae87da to f6190e7 Compare August 8, 2023 02:29
@erights erights force-pushed the markm-options-harmony branch 3 times, most recently from b0abc60 to 11e8047 Compare August 21, 2023 23:23
@erights erights force-pushed the markm-options-harmony branch 3 times, most recently from c8cbe6f to e28ac45 Compare August 29, 2023 05:05
@erights
Copy link
Copy Markdown
Contributor Author

erights commented Aug 29, 2023

See also nodejs/node#48890

@erights erights force-pushed the markm-options-harmony branch 2 times, most recently from 8515a62 to d692fac Compare August 30, 2023 01:21
@erights erights force-pushed the markm-options-harmony branch 2 times, most recently from 2ce5dd0 to a7664ac Compare September 16, 2023 02:45
@erights erights force-pushed the markm-options-harmony branch 2 times, most recently from 695c347 to 7799061 Compare September 26, 2023 03:13
@erights erights force-pushed the markm-options-harmony branch from 7799061 to 77aea46 Compare October 3, 2023 20:26
@erights erights force-pushed the markm-options-harmony branch from 77aea46 to 7577a77 Compare October 13, 2023 22:33
@erights erights force-pushed the markm-options-harmony branch from 7577a77 to 1a0dd3e Compare October 24, 2023 23:33
@erights erights force-pushed the markm-options-harmony branch 2 times, most recently from 7383ed9 to e1199d3 Compare November 7, 2023 19:21
@erights erights force-pushed the markm-options-harmony branch from e1199d3 to 30bd756 Compare November 12, 2023 04:44
@erights erights force-pushed the markm-options-harmony branch from 30bd756 to 59b523f Compare December 21, 2023 03:21
@erights erights force-pushed the markm-options-harmony branch 3 times, most recently from 43ed48f to 19b3465 Compare December 31, 2023 23:51
@erights erights changed the title WIP fix(env-options)!: env-options harmony feat(env-options): env-options conveniences for common cases Dec 31, 2023
@erights erights force-pushed the markm-options-harmony branch from 19b3465 to c15595d Compare January 1, 2024 00:10
@erights erights requested a review from kriskowal January 1, 2024 00:12
@erights erights requested a review from dckc January 1, 2024 00:12
@erights erights marked this pull request as ready for review January 1, 2024 00:12
@erights erights force-pushed the markm-options-harmony branch from c15595d to 2f05b1a Compare January 1, 2024 00:13
@erights erights requested a review from gibson042 January 1, 2024 00:31
@erights erights force-pushed the markm-options-harmony branch from 2f05b1a to a8e1407 Compare January 5, 2024 04:19
@erights erights requested a review from michaelfig January 8, 2024 19:34
@erights erights force-pushed the markm-options-harmony branch 2 times, most recently from 6926eb8 to a802aa5 Compare January 8, 2024 21:46
@dckc dckc removed their request for review January 8, 2024 22:10
@erights erights force-pushed the markm-options-harmony branch 3 times, most recently from e130e8c to ac480ad Compare January 10, 2024 00:42
Copy link
Copy Markdown
Member

@michaelfig michaelfig left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM!

Comment thread packages/env-options/src/env-options.js Outdated
Copy link
Copy Markdown
Member

@gibson042 gibson042 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM after minor fixes.

Comment thread packages/env-options/README.md Outdated
Comment thread packages/env-options/README.md Outdated
Comment thread packages/env-options/README.md Outdated
Comment thread packages/env-options/README.md Outdated
Comment thread packages/env-options/src/env-options.js Outdated
Comment thread packages/env-options/src/env-options.js Outdated
@erights erights force-pushed the markm-options-harmony branch from ac480ad to c2dad51 Compare January 10, 2024 21:12
@erights erights enabled auto-merge (squash) January 10, 2024 21:15
@erights erights merged commit 4c686f6 into master Jan 10, 2024
@erights erights deleted the markm-options-harmony branch January 10, 2024 21:18
erights added a commit that referenced this pull request May 13, 2025
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.
boneskull pushed a commit that referenced this pull request Jun 4, 2025
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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants