feat: Support configuring Parseable via TOML config file

[niladrix719]

Fixes #1157

Description

Goal: allow configuring Parseable via a TOML file so users don’t juggle dozens of P_* env vars.

Approach: load a config file before Clap runs, hydrate env defaults, and let CLI/env overrides keep their precedence.

Key changes: new config_loader, --config-file flag, added toml dependency, docs/tests for the workflow

---

This PR has:

• [x] been tested to ensure log ingestion and log query works.
• [x] added comments explaining the "why" and the intent of the code wherever would not be obvious for an unfamiliar reader.
• [x] added documentation for new or modified features or behaviors.

Summary by CodeRabbit

• New Features

  • TOML configuration support for environment defaults (defaults to parseable.toml)
  • New CLI option to specify a custom config file
  • Config values map to environment variables with CLI flags taking precedence
  • Storage backend selection via TOML, with automatic injection when configured

• Documentation

  • Added "Configure with TOML" guide and examples to the README

• Tests

  • Added tests covering config-driven CLI behavior and environment handling

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai[bot]]

Walkthrough

Adds TOML-based configuration loading and a CLI option to specify a TOML file; introduces a new config loader that reads/merges a TOML file into environment defaults, can inject storage settings into CLI args, and updates initialization to select among multiple storage backends.

Changes

Cohort / File(s)	Summary
Dependency addition Cargo.toml	Added toml = "0.8" dependency for TOML parsing.
Documentation README.md	Added "Configure with TOML" section describing automatic parseable.toml loading, --config-file / P_CONFIG_FILE, config-to-env mapping, and precedence (CLI flags > env > TOML).
CLI augmentation src/cli.rs	Added pub config_file: Option<PathBuf> to Cli with --config-file / -c, environment fallback P_CONFIG_FILE, and file_path validation.
Configuration loading module src/config_loader.rs	New module providing pub fn parse_cli_with_config() -> Cli, config discovery (locate_config_file), TOML parsing into FileConfig, merging inline & top-level env maps, applying env overrides only for unset vars, recording resolved P_CONFIG_FILE, injecting storage args when absent, global ENV_LOCK to serialize env mutations, contextual errors, and tests.
Module integration src/lib.rs	Added mod config_loader; to include the new module.
Initialization refactor src/parseable/mod.rs	Replaced Cli::parse() with parse_cli_with_config(); expanded storage initialization to handle multiple backends (Local, S3, Blob, Gcs), constructed appropriate metastore per backend, adjusted imports, and adapted error-handling paths.

Sequence Diagram(s)

sequenceDiagram
    autonumber
    participant App as Application
    participant Loader as config_loader
    participant FS as File System
    participant TOML as TOML Parser
    participant Env as Environment
    participant CLI as Clap Parser
    participant Init as Storage Init

    App->>Loader: parse_cli_with_config()
    Loader->>Loader: locate_config_file(args, env, default)
    alt config file found
        Loader->>FS: read file
        FS-->>Loader: contents
        Loader->>TOML: parse -> FileConfig
        TOML-->>Loader: FileConfig
        Loader->>Loader: merge inline & top-level env maps
        Loader->>Env: set missing P_* vars (skip existing)
        Loader->>Env: set P_CONFIG_FILE if unset
    else no config
        Loader-->>Loader: continue with args/env
    end
    Loader->>Loader: inject storage args if no storage subcommand
    Loader->>CLI: parse (possibly modified) args into Cli
    CLI-->>Loader: Cli
    Loader-->>App: Cli with resolved config
    App->>Init: initialize chosen storage backend (Local/S3/Blob/Gcs)
    Init-->>App: Parseable instance

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

• Review config discovery precedence (CLI arg > existing env > TOML).
• Inspect ENV_LOCK usage and environment mutation safety.
• Verify storage-argument injection and error paths in src/parseable/mod.rs.
• Check TOML parsing/merging (inline vs top-level env maps) and tests in src/config_loader.rs.

Poem

In burrows of code I hop and compile,
A TOML tucked in makes defaults worthwhile.
I nudge the env gently, never overwrite,
CLI leads the chorus, options shine bright.
Hooray — storage chosen, the rabbit's delight! 🐰

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title accurately and concisely describes the main feature: adding TOML config file support to Parseable.
Description check	✅ Passed	The PR description includes issue reference, clear goal/approach/key changes, and all checklist items marked complete with evidence of testing and documentation.
Linked Issues check	✅ Passed	The PR implementation fully addresses issue #1157 by enabling TOML file configuration, simplifying env var management, and preserving proper precedence hierarchy.
Out of Scope Changes check	✅ Passed	All changes are scoped to TOML config support: dependency addition, CLI flag, config loader module, and storage initialization updates are all directly related to the stated objective.

✨ Finishing touches

🧪 Generate unit tests (beta)

• [ ] Create PR with unit tests
• [ ] Post copyable unit tests in a comment

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 1d0aed0dda498355d2ff3a8e4b42675c71cf3f88 and 936b273aba0fb0aaf289defc08d118c78c5b947a.

⛔ Files ignored due to path filters (1)

• Cargo.lock is excluded by !**/*.lock

📒 Files selected for processing (1)

• Cargo.toml (1 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

• Cargo.toml

[!TIP]

📝 Customizable high-level summaries are now available in beta!

You can now customize how CodeRabbit generates the high-level summary in your pull requests — including its content, structure, tone, and formatting.

• Provide your own instructions using the high_level_summary_instructions setting.
• Format the summary however you like (bullet lists, tables, multi-section layouts, contributor stats, etc.).
• Use high_level_summary_in_walkthrough to move the summary from the description to the walkthrough section.

Example instruction:

"Divide the high-level summary into five sections:

1. 📝 Description — Summarize the main change in 50–60 words, explaining what was done.
2. 📓 References — List relevant issues, discussions, documentation, or related PRs.
3. 📦 Dependencies & Requirements — Mention any new/updated dependencies, environment variable changes, or configuration updates.
4. 📊 Contributor Summary — Include a Markdown table showing contributions: | Contributor | Lines Added | Lines Removed | Files Changed |
5. ✔️ Additional Notes — Add any extra reviewer context. Keep each section concise (under 200 words) and use bullet or numbered lists for clarity."

Note: This feature is currently in beta for Pro-tier users, and pricing will be announced later.

---

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.}

[github-actions[bot]]

CLA Assistant Lite bot All contributors have signed the CLA ✍️ ✅

[niladrix719]

I have read the CLA Document and I hereby sign the CLA

[nitisht]

@niladrix719 can you address the build failures?

[niladrix719]

@niladrix719 can you address the build failures?

Done