env: add bash-style default value operator :-

[benjaminmueggenburg-serato]

Adds the familiar bash-style default value operator :-.
Now inside configuration files ${VALUE:-default} will resolve to default if VALUE variable is not set (os or locally) or is empty ''.

Addresses #5517

Configuration example

Expand

[SERVICE]
    flush        1
    log_level    info
[INPUT]
    name         cpu
    tag          cpu.local
    interval_sec 1
[FILTER]
    name         record_modifier
    match        *
    record       env_check ${TEST_ZONE:-default-region}
[OUTPUT]
    name         stdout
    match        *
    format       json_lines

---

Checklist (maintainers)

• Debug log output from testing the change

Debug / stdout

Unset TEST_ZONE

{"date":1778203458.250104,"cpu_p":1.2,"user_p":1.0,"system_p":0.2,"cpu0.p_cpu":2.0,"cpu0.p_user":1.0,"cpu0.p_system":1.0,"cpu1.p_cpu":1.0,"cpu1.p_user":1.0,"cpu1.p_system":0.0,"env_check":"default-region"}
{"date":1778203459.23832,"cpu_p":0.9,"user_p":0.5,"system_p":0.4,"cpu0.p_cpu":1.0,"cpu0.p_user":1.0,"cpu0.p_system":0.0,"cpu1.p_cpu":1.0,"cpu1.p_user":1.0,"cpu1.p_system":0.0,"env_check":"default-region"}

Set TEST_ZONE=eu-west-1:

{"date":1778203774.244381,"cpu_p":0.2,"user_p":0.2,"system_p":0.0,"cpu0.p_cpu":0.0,"cpu0.p_user":0.0,"cpu0.p_system":0.0,"cpu1.p_cpu":0.0,"cpu1.p_user":0.0,"cpu1.p_system":0.0,"env_check":"eu-west-1"}
{"date":1778203775.24408,"cpu_p":0.5,"user_p":0.1,"system_p":0.4,"cpu0.p_cpu":1.0,"cpu0.p_user":0.0,"cpu0.p_system":1.0,"cpu1.p_cpu":0.0,"cpu1.p_user":0.0,"cpu1.p_system":0.0,"env_check":"eu-west-1"}

Unit tests

$ ctest --test-dir build -L internal --output-on-failure

[...]
    Start 39: flb-it-env
1/1 Test #39: flb-it-env .......................   Passed    2.21 sec
[...]

100% tests passed, 0 tests failed out of 83

Label Time Summary:
internal    = 109.64 sec*proc (83 tests)

Total Test time (real) = 109.78 sec

• Attached Valgrind output that shows no leaks or memory corruption

Valgrind summary / log tail

Command:

$ valgrind --leak-check=full --error-exitcode=1 ./build/bin/flb-it-env

Valgrind tail:

==18604== Memcheck, a memory error detector
==18604== Copyright (C) 2002-2017, and GNU GPL'd, by Julian Seward et al.
==18604== Using Valgrind-3.18.1 and LibVEX; rerun with -h for copyright info
==18604== Command: ./build/bin/flb-it-env
==18604== 
Test translate_long_env...                      [ OK ]
==18604== Warning: invalid file descriptor -1 in syscall close()
Test file_env_var_basic...                      [ OK ]
==18604== Warning: invalid file descriptor -1 in syscall close()
Test file_env_var_refresh...                    [ OK ]
==18604== Warning: invalid file descriptor -1 in syscall close()
Test file_env_var_uri...                        [ OK ]
==18604== Warning: invalid file descriptor -1 in syscall close()
Test mixed_env_vars...                          [ OK ]
==18604== Warning: invalid file descriptor -1 in syscall close()
Test file_env_var_missing...                    [2026/05/08 01:38:44.657] [error] [env] file flb_nonexistent_file.txt not found
[2026/05/08 01:38:44.700] [ warn] [env] variable ${MISSING_VAR} is used but not set
[ OK ]
==18604== Warning: invalid file descriptor -1 in syscall close()
Test expand_default_hyphen...                   [ OK ]
==18604== Warning: invalid file descriptor -1 in syscall close()
Test expand_empty_default...                    [ OK ]
==18604== Warning: invalid file descriptor -1 in syscall close()
Test expand_default_hyphen_from_os...           [ OK ]
==18604== Warning: invalid file descriptor -1 in syscall close()
SUCCESS: All unit tests have passed.
==18604== 
==18604== HEAP SUMMARY:
==18604==     in use at exit: 0 bytes in 0 blocks
==18604==   total heap usage: 9,703 allocs, 9,703 frees, 1,119,355 bytes allocated
==18604== 
==18604== All heap blocks were freed -- no leaks are possible
==18604== 
==18604== For lists of detected and suppressed errors, rerun with: -s
==18604== ERROR SUMMARY: 0 errors from 0 contexts (suppressed: 0 from 0)

If this is a change to packaging of containers or native binaries then please confirm it works for all targets.

• [N/A] Run local packaging test showing all targets (including any new ones) build.
• [N/A] Set ok-package-test label to test for all targets (requires maintainer to do).

Documentation

• Documentation required for this feature

fluent/fluent-bit-docs#2568

Backporting

• Backport to latest stable release.

---

Fluent Bit is licensed under Apache 2.0, by submitting this pull request I understand that this code will be released under the terms of that license.

Summary by CodeRabbit

Release Notes

• New Features

  • Added bash-style default substitution support for environment variables. Expressions like ${VAR:-fallback} now expand to the fallback value when the variable is unset or empty.

• Tests

  • Added test coverage for default substitution scenarios, including unset variables, empty string values, and OS environment variable integration.

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR adds bash-style default substitution syntax ${VAR:-fallback} to fluent-bit's environment variable expansion function. When a referenced variable is unset or empty, the fallback value is used instead of omitting the placeholder. Implementation includes parsing logic to detect and extract the :- pattern, conditional adjustments for empty/unset handling, and comprehensive test coverage for all usage scenarios including OS environment integration.

Changes

Environment Variable Default Substitution

Layer / File(s)	Summary
Feature Specification src/flb_env.c	Function documentation updated to describe ${name:-word} bash-style default substitution behavior and expansion semantics.
Token Parsing & Fallback Extraction src/flb_env.c	Added logic to detect the :- separator within ${...} tokens, split into variable name and fallback string, and prepare fallback length for appending.
Semantic Handling src/flb_env.c	Conditional logic adjusted so env lookup is treated as "usable" only when non-empty when a fallback is defined; "warn_unused" warning skipped when valid fallback exists and env is empty or unset.
Fallback Expansion src/flb_env.c	Implemented fallback path: when env var is missing or empty and fallback exists, fallback content is appended to output buffer with allocation failure handling.
Test Coverage tests/internal/env.c	Added test cases for: unset variables with fallback, empty variable values with fallback, empty fallbacks, and OS environment integration; test registration updated.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 A variable whispers, "What if I'm not there?"
The colon-dash answers with fallback so fair—
Default values blossom where empties once grew,
Bash-style expansion makes shells happy too! 🌿

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'env: add bash-style default value operator :-' is specific and directly describes the main feature added: bash-style default substitution support in environment variable handling.
Docstring Coverage	✅ Passed	Docstring coverage is 80.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[patrick-stephens]

Super useful and makes things a lot more consistent with the usage of the ${} syntax.