Repository navigation
feat(discovery): XCIND_ENV_MAP — app-defined names for discovery variables - #101
Merged
Merged
Conversation
…ables
Let an app declare its own variable names as templates over XCIND_*
discovery variables:
XCIND_ENV_MAP+=('DATABASE_HOST=${XCIND_SHOP_DATABASE_HOST}')
Each template is expanded from each view's pair set and appended after
the XCIND_* variables: to every service's environment in
compose.discovery.yaml, and to the XCIND_HOST_ENV_FILE body. A
reference missing from one view drops the entry from that view only; a
reference missing from both views fails generation.
Templates allow literal text plus ${XCIND_[A-Z0-9_]+} references. Any
other $, a backslash, a backtick, or a control character is an error,
so no rendered value can be changed by Compose interpolation or dotenv
expansion, and an entry can never split into extra env entries. Keys
must be valid env names and must not start with XCIND_. Identical
repeats are emitted once; conflicting repeats fail.
The discovery hook validates the map syntax before its yq soft-skip.
xcind-config --json reports the declared templates under envMap.
Recorded in ADR-0025 as a PROMOTE candidate (XA-0046).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
An app can now give its own names to discovery values. Each name is a template over
XCIND_*discovery variables, and Xcind renders it with the right value for each view:environment:incompose.discovery.yaml, after theXCIND_*variables.XCIND_HOST_ENV_FILEbody, after theXCIND_*variables.With an assigned
databaseexport,DATABASE_HOSTisshop-databasein a container and127.0.0.1(or the assigned hostname) in the host env file.Why
Today an app maps names in a dotenv file (
DATABASE_HOST=${XCIND_SHOP_DATABASE_HOST}). Only a process that loads that file with expansion sees the value. Other tools in the same container, such as a database CLI, a Node service, or a shell script, do not. Compose cannot do the mapping either, because it interpolates from the shell that runs it, not from the variables that Xcind injects.Rules
The full contract is in ADR-0025.
${XCIND_[A-Z0-9_]+}references. Any other$, a backslash, a backtick, or a control character is an error. So no rendered value contains$, Compose interpolation and dotenv expansion cannot change a value, and an entry cannot split into extra env entries.unpublishedexport is absent from the host file). A reference missing from both views fails generation and names the entry.XCIND_. Identical repeats are emitted once. The same key with two templates is an error.environment:orenv_file:. This is documented, with no warning.yqsoft-skip, so a syntax error fails generation even when the overlay is skipped.xcind-config --jsonreports the declared templates under a newenvMapkey. It shows the last template for a repeated key and does not validate.When the map is not set, the generated overlay and host env file are byte-identical to
main.How
lib/xcind/xcind-discovery-lib.bash: new__xcind-discovery-validate-env-map(syntax only),__xcind-discovery-envmap-expand(scans the string, noeval), and__xcind-discovery-build-mapped-pairs <app_root> <view> [own_view_pairs]. The builder computes the other view so that it can detect a reference missing from both. Each hook passes in the view it already built, so a non-empty map adds one extra pair build per hook.xcind-discovery-hookand__xcind-hostenv-execute-hookappend the mapped pairs and fail on any map error. On failure the host env file is not written, and inblockmode it stays byte-identical.lib/xcind/xcind-lib.bashaddsenvMapto the JSON contract. Thexcind-confighelp and the bash and zsh completions list it.Tests
New cases in
test/test-xcind.sh:$form, and control characters, backslash, and backtick (including a newline-injection case).XCIND_keys, and identical and conflicting repeats.yq.blockmode keeps an existing file unchanged on error.envMapJSON key: set, unset, multi-line, and last-wins.make checkpasses with 0 failures. An Opus review found one defect: a newline in an entry injected extra env entries. That defect and four smaller findings are fixed in this PR. A live check on a real workspace confirmed both views. A database CLI in a container and a client on the host both connected using only the mapped names, and a reference typo failedxcind-compose config.Docs
env_map:block inapplication.yaml(ledger row XA-0046, plus a correspondence-map row).