docs(rfc): configuration file — YAML + env substitution (RFC 0020) - #320
Conversation
|
Warning Review limit reached
Next review available in: 20 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (2)
📝 WalkthroughWalkthroughAdds RFC 0020, a new 336-line document specifying a YAML-based server configuration file mechanism with environment-variable substitution, schema definition, alternatives considered, acceptance criteria, testing strategy, and open questions. Also adds the corresponding entry in ChangesRFC 0020 — Configuration File
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
There was a problem hiding this comment.
Pull request overview
This PR adds the RFC 0020 specification describing a new ourios-server YAML configuration file selected via --config <path>, including OpenTelemetry-style environment-variable substitution, and indexes it in the docs RFC summary.
Changes:
- Adds RFC 0020 describing the configuration-file mode, substitution rules, schema shape, and acceptance scenarios.
- Updates the mdBook
docs/SUMMARY.mdto include RFC 0020 in the RFC list.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| docs/SUMMARY.md | Adds RFC 0020 to the RFC index so it appears in the rendered book. |
| docs/rfcs/0020-configuration-file.md | Introduces the full RFC 0020 spec for YAML config + env substitution and acceptance criteria. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
🧹 Nitpick comments (1)
docs/rfcs/0020-configuration-file.md (1)
96-100: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick winFix undefined non-terminals and notation label in §3.3 grammar.
The grammar block uses
GENERIC-SUBSTITUTION(line 97) which is never defined — onlyENV-SUBSTITUTION(line 98) exists.PREFIX(line 97) is also undefined. Additionally, the parenthetical calls this "PCRE2", but the notation is ABNF-style, not PCRE2.📝 Proposed fix
-The grammar (non-normative PCRE2, normative ABNF is the WG spec): +The grammar (non-normative ABNF; normative ABNF is the WG spec): ```text -SUBSTITUTION-REF = ${ (PREFIX ":")? GENERIC-SUBSTITUTION } +SUBSTITUTION-REF = ${ ( ( "env" ":" )? ENV-SUBSTITUTION ) } ENV-SUBSTITUTION = ENV-NAME ( ":-" DEFAULT-VALUE )? ENV-NAME = [A-Za-z_][A-Za-z0-9_]*</details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.In
@docs/rfcs/0020-configuration-file.mdaround lines 96 - 100, Fix the §3.3
grammar so it only references defined non-terminals and uses the correct
notation label. Update the SUBSTITUTION-REF rule to point to ENV-SUBSTITUTION
instead of the undefined GENERIC-SUBSTITUTION, and replace the undefined PREFIX
token with the intended literal prefix form in the same grammar block. Also
change the parenthetical label from PCRE2 to ABNF-style notation to match the
syntax used by ENV-SUBSTITUTION and ENV-NAME.</details> <!-- cr-comment:v1:37b5d7f7fee12575bd475c73 --> </blockquote></details> </blockquote></details> <details> <summary>🤖 Prompt for all review comments with AI agents</summary>Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.Nitpick comments:
In@docs/rfcs/0020-configuration-file.md:
- Around line 96-100: Fix the §3.3 grammar so it only references defined
non-terminals and uses the correct notation label. Update the SUBSTITUTION-REF
rule to point to ENV-SUBSTITUTION instead of the undefined GENERIC-SUBSTITUTION,
and replace the undefined PREFIX token with the intended literal prefix form in
the same grammar block. Also change the parenthetical label from PCRE2 to
ABNF-style notation to match the syntax used by ENV-SUBSTITUTION and ENV-NAME.</details> --- <details> <summary>ℹ️ Review info</summary> <details> <summary>⚙️ Run configuration</summary> **Configuration used**: defaults **Review profile**: CHILL **Plan**: Pro Plus **Run ID**: `fd531807-6a5a-4221-8896-bc14d81ce0cb` </details> <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between 697b771f224ecad715be66238806a82f94e58c31 and 3110d5f999af95dfd96cae72bbd0e92dfb24fea6. </details> <details> <summary>📒 Files selected for processing (2)</summary> * `docs/SUMMARY.md` * `docs/rfcs/0020-configuration-file.md` </details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
e622967 to
df158fd
Compare
df158fd to
7026d00
Compare
…ecified)
A YAML config file for ourios-server (--config <path>) holding Ourios's
own data-plane tunables (storage / receiver / querier / compaction), with
OpenTelemetry-Config-WG env substitution (${env:NAME}/${NAME}, :-default,
$$ escape; on parsed scalar VALUES only — keys never candidates, results
never re-parsed into structure; type resolved on the substituted scalar;
malformed ${…} refs in value position are a whole-file error; undefined-
no-default is style-dependent). File-authoritative when --config is given;
the pure-OURIOS_*-env path is unchanged when absent (non-breaking).
Scope boundary (§3.8): the standard OTEL_* SDK environment is deliberately
NOT modeled in the config — it configures Ourios's own telemetry SDK and
is read by the SDK directly per the OTel env-var spec (no otel: section).
RFC 0004 stays the *what* (tunables vs invariants); this is the *how*.
6 §5 scenarios (RFC0020.1-.6). Held for maintainer sign-off (§5.3).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
7026d00 to
610f4c9
Compare
What
Specifies RFC 0020 — Server configuration file: a YAML config for
ourios-server, selected with--config <path>, with OpenTelemetry-Config-WG-style environment-variable substitution (${env:NAME},${NAME},${env:NAME:-default},$$escape; scalar-only, non-recursive).Per the maintainer's two design decisions:
--configis given, config comes from the file; env participates only via${env:…}inside it. No--config→ today's pure-OURIOS_*-env path, unchanged (non-breaking).ServerConfig, one validation path.Scope
${env:…}(never inline); extends RFC 0019 §3.4 secret-hygiene to the file path.RFC0020.1–.6). Helm chart migration to a ConfigMap is a tracked follow-on, out of scope here.Status
specified(§§1–8 complete, §5 scenarios have ids). Holding implementation for maintainer sign-off perCLAUDE.md§5.3 — this PR is the spec to review/sign off, not a code change. Open questions in §7.🤖 Generated with Claude Code
Summary by CodeRabbit