From 09f05210c27bbec192869a7462687d691ccb389b Mon Sep 17 00:00:00 2001 From: Yusef Mohamadi Date: Thu, 25 Dec 2025 23:39:59 +0100 Subject: [PATCH 1/3] chore: update go version + update readme --- README.md | 288 ++++++++++++++++++++++++++++++++++++++++-------------- go.mod | 6 +- go.sum | 4 + 3 files changed, 219 insertions(+), 79 deletions(-) diff --git a/README.md b/README.md index 774ec2c..fa11563 100644 --- a/README.md +++ b/README.md @@ -1,132 +1,268 @@ -# envYaml (Yaml with environment value loader) +
-[![codecov](https://codecov.io/github/yuseferi/envyaml/graph/badge.svg?token=0DUS258IUD)](https://codecov.io/github/yuseferi/envyaml) -[![Check & Build](https://github.com/yuseferi/envyaml/actions/workflows/ci.yml/badge.svg)](https://github.com/yuseferi/envyaml/actions/workflows/ci.yml) -[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0) -![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/yuseferi/envyaml) -[![Go Report Card](https://goreportcard.com/badge/github.com/yuseferi/envyaml)](https://goreportcard.com/report/github.com/yuseferi/envyaml) +# πŸ” envYaml -

- +### Seamlessly merge YAML configuration with environment variables + +[![Go Version](https://img.shields.io/badge/Go-1.25+-00ADD8?style=for-the-badge&logo=go&logoColor=white)](https://go.dev/) +[![codecov](https://img.shields.io/codecov/c/github/yuseferi/envyaml?style=for-the-badge&logo=codecov&logoColor=white)](https://codecov.io/github/yuseferi/envyaml) +[![CI](https://img.shields.io/github/actions/workflow/status/yuseferi/envyaml/ci.yml?style=for-the-badge&logo=github&label=CI)](https://github.com/yuseferi/envyaml/actions/workflows/ci.yml) +[![Go Report Card](https://goreportcard.com/badge/github.com/yuseferi/envyaml?style=for-the-badge)](https://goreportcard.com/report/github.com/yuseferi/envyaml) +[![License](https://img.shields.io/badge/License-GPL_v3-blue?style=for-the-badge)](LICENSE) +[![Release](https://img.shields.io/github/v/release/yuseferi/envyaml?style=for-the-badge&logo=github)](https://github.com/yuseferi/envyaml/releases) + +

+envYaml Logo

-Storing application configuration in YAML files offers a clean and straightforward solution, but it's crucial to avoid exposing sensitive data like passwords and API keys. Environment variables provide a secure way to store secrets, preventing them from leaking into your codebase. +**Keep your configuration clean. Keep your secrets safe.** + +[Installation](#-installation) β€’ +[Quick Start](#-quick-start) β€’ +[Features](#-features) β€’ +[Examples](#-examples) β€’ +[Contributing](#-contributing) -The **envyaml** package bridges this gap, allowing you to seamlessly integrate environment variables into your YAML configuration. No more plain-text secrets or complex workarounds! Simply reference environment variables within your YAML file using placeholders, and envyaml will handle the rest, securely substituting the values during parsing. +--- -With **envyaml**, you can: +
-- Keep your configuration clean and organized in YAML. -- Protect sensitive data by storing it in environment variables. -- Enjoy a simple and intuitive integration process. -- No more compromising between convenience and security. **envyaml** empowers you to manage your application configuration effectively while keeping your secrets safe. +## 🎯 The Problem -## Installation +You love YAML for configurationβ€”it's clean, readable, and organized. But what about sensitive data like API keys, database passwords, and tokens? Hardcoding them is a security nightmare. 😱 -To install envyaml, use `go get`: +## ✨ The Solution +**envYaml** bridges the gap between clean YAML configuration and secure environment variable management. Reference environment variables directly in your YAML files, and envYaml handles the rest! + +```yaml +# config.yml - Clean and secure! πŸ”’ +database: + host: localhost + port: 5432 + password: ${DB_PASSWORD} # Loaded from environment + +api: + key: ${API_KEY} # Never committed to git + secret: ${API_SECRET} # Always secure ``` + +## πŸš€ Installation + +```bash go get github.com/yuseferi/envyaml@latest ``` -## Usage +**Requirements:** Go 1.25+ + +## ⚑ Quick Start + +**1. Create your YAML configuration:** -### Example 1: Error on required env variable +```yaml +# config.yml +host: localhost +port: 3606 +password: ${DB_PASSWORD} +``` + +**2. Define your config struct:** ```go -type TestConfig struct { - Host string `yaml:"host" env:"TEST_HOST"` - Port int `yaml:"port" env:"TEST_PORT"` - Password string `yaml:"password" env:"TEST_PASSWORD,required"` +type Config struct { + Host string `yaml:"host" env:"HOST"` + Port int `yaml:"port" env:"PORT"` + Password string `yaml:"password" env:"DB_PASSWORD,required"` } +``` -// Load the configuration -var cfg TestConfig -// assume your configs are in `config.yml` file and this is its content: -//host: localhost -//port: 3606 -//password: ${TEST_PASSWORD} -err := envyaml.LoadConfig("config.yml", &cfg) -if err != nil { - log.Fatalln(err) +**3. Load and use:** + +```go +package main + +import ( + "fmt" + "log" + + "github.com/yuseferi/envyaml" +) + +func main() { + var cfg Config + + if err := envyaml.LoadConfig("config.yml", &cfg); err != nil { + log.Fatal(err) + } + + fmt.Printf("Connected to %s:%d\n", cfg.Host, cfg.Port) } -fmt.Println(cfg) ``` -Error `failed to parse environment variables: env: required environment variable "TEST_PASSWORD" is not set` is expected because this variable has not been set. +## 🎨 Features + +| Feature | Description | +|---------|-------------| +| πŸ”„ **Seamless Integration** | Combine YAML files with environment variables effortlessly | +| βœ… **Required Variables** | Mark critical env vars as required with automatic validation | +| 🏷️ **Struct Tags** | Use familiar `yaml` and `env` struct tags | +| πŸ›‘οΈ **Type Safety** | Full Go type safety with automatic type conversion | +| πŸ“¦ **Zero Config** | Works out of the box with sensible defaults | +| πŸͺΆ **Lightweight** | Minimal dependencies, maximum performance | + +## πŸ“š Examples -### Example 2: When env is defined +### Required Environment Variables + +Mark sensitive variables as required to fail fast if they're missing: ```go -type TestConfig struct { - Host string `yaml:"host" env:"TEST_HOST"` - Port int `yaml:"port" env:"TEST_PORT"` - Password string `yaml:"password" env:"TEST_PASSWORD,required"` +type Config struct { + Host string `yaml:"host" env:"HOST"` + Port int `yaml:"port" env:"PORT"` + Password string `yaml:"password" env:"DB_PASSWORD,required"` // πŸ‘ˆ Required! } -// Load the configuration -var cfg TestConfig -// assume your configs are in `config.yml` file and this is its content: -//host: localhost -//port: 3606 -//password: ${TEST_PASSWORD} -_ = os.Setenv("TEST_PASSWORD", "envyaml_pass") +var cfg Config err := envyaml.LoadConfig("config.yml", &cfg) if err != nil { -log.Fatalln(err) -log.Fatalln(err) + // Error: failed to parse environment variables: env: required environment variable "DB_PASSWORD" is not set + log.Fatal(err) +} +``` - log.Fatalln(err) +### Complete Working Example +```go +package main + +import ( + "fmt" + "log" + "os" + + "github.com/yuseferi/envyaml" +) + +type DatabaseConfig struct { + Host string `yaml:"host" env:"DB_HOST"` + Port int `yaml:"port" env:"DB_PORT"` + Username string `yaml:"username" env:"DB_USER"` + Password string `yaml:"password" env:"DB_PASSWORD,required"` + Database string `yaml:"database" env:"DB_NAME"` } -fmt.Println(cfg) -``` -Expected output: -``` -{localhost 3606 envyaml_pass} +type Config struct { + Database DatabaseConfig `yaml:"database"` + Debug bool `yaml:"debug" env:"DEBUG"` +} + +func main() { + // Set environment variables (in production, these come from your environment) + os.Setenv("DB_PASSWORD", "super_secret_password") + + var cfg Config + if err := envyaml.LoadConfig("config.yml", &cfg); err != nil { + log.Fatalf("Failed to load config: %v", err) + } + + fmt.Printf("Database: %s@%s:%d/%s\n", + cfg.Database.Username, + cfg.Database.Host, + cfg.Database.Port, + cfg.Database.Database, + ) +} ``` -## Development +With this `config.yml`: -This project uses [Task](https://taskfile.dev) for managing development tasks. Make sure you have Task installed on your system. +```yaml +database: + host: localhost + port: 5432 + username: admin + password: ${DB_PASSWORD} + database: myapp -### Available Tasks +debug: false +``` -- `task build`: Build the project -- `task test`: Run tests -- `task test-coverage`: Run tests with coverage and generate a coverage report -- `task clean`: Clean up generated files -- `task all`: Run all tasks (build, test, and coverage) +**Output:** +``` +Database: admin@localhost:5432/myapp +``` -To run a task, use the `task` command followed by the task name. For example: +## πŸ—οΈ How It Works ``` -task build +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ YAML File β”‚ β”‚ Environment β”‚ β”‚ Go Struct β”‚ +β”‚ β”‚ β”‚ Variables β”‚ β”‚ β”‚ +β”‚ host: localhostβ”‚ β”‚ β”‚ β”‚ Host: localhostβ”‚ +β”‚ port: 3606 β”‚ ──► β”‚ DB_PASSWORD= β”‚ ──► β”‚ Port: 3606 β”‚ +β”‚ password: ${..}β”‚ β”‚ "secret123" β”‚ β”‚ Password: ... β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ β”‚ β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + envYaml ``` -### Running Tests +1. **Read** - Parse your YAML configuration file +2. **Merge** - Overlay environment variables using struct tags +3. **Validate** - Ensure required variables are present +4. **Return** - Provide a fully populated, type-safe config struct -To run tests: +## πŸ› οΈ Development -``` -task test -``` +This project uses [Task](https://taskfile.dev) for managing development tasks. -To run tests with coverage: +```bash +# Build the project +task build -``` +# Run tests +task test + +# Run tests with coverage task test-coverage + +# Clean generated files +task clean + +# Run all tasks +task all ``` -This will generate a coverage report in HTML format (`coverage.html`). +## 🀝 Contributing + +We love contributions! ❀️ + +1. 🍴 Fork the repository +2. 🌿 Create your feature branch (`git checkout -b feature/amazing-feature`) +3. πŸ’Ύ Commit your changes (`git commit -m 'Add amazing feature'`) +4. πŸ“€ Push to the branch (`git push origin feature/amazing-feature`) +5. πŸŽ‰ Open a Pull Request + +Please feel free to: +- πŸ› Report bugs +- πŸ’‘ Suggest new features +- πŸ“– Improve documentation +- ⭐ Star the project if you find it useful! + +## πŸ“„ License + +This project is licensed under the **GNU General Public License v3.0** - see the [LICENSE](LICENSE) file for details. -## Contributing +--- -We strongly believe in open-source ❀️😊. Please feel free to contribute by raising issues and submitting pull requests to make envYaml even better! +
-## License +**Made with ❀️ by [Yusef Mohamadi](https://github.com/yuseferi)** -Released under the [GNU GENERAL PUBLIC LICENSE](LICENSE). +If this project helped you, consider giving it a ⭐! +[![GitHub stars](https://img.shields.io/github/stars/yuseferi/envyaml?style=social)](https://github.com/yuseferi/envyaml/stargazers) +[![GitHub forks](https://img.shields.io/github/forks/yuseferi/envyaml?style=social)](https://github.com/yuseferi/envyaml/network/members) +
diff --git a/go.mod b/go.mod index a81563f..0786aae 100644 --- a/go.mod +++ b/go.mod @@ -1,10 +1,10 @@ module github.com/yuseferi/envyaml -go 1.22.0 +go 1.25 require ( - github.com/caarlos0/env/v11 v11.2.2 - github.com/stretchr/testify v1.9.0 + github.com/caarlos0/env/v11 v11.3.1 + github.com/stretchr/testify v1.11.1 gopkg.in/yaml.v3 v3.0.1 ) diff --git a/go.sum b/go.sum index 042c1e1..1b1a4b7 100644 --- a/go.sum +++ b/go.sum @@ -1,11 +1,15 @@ github.com/caarlos0/env/v11 v11.2.2 h1:95fApNrUyueipoZN/EhA8mMxiNxrBwDa+oAZrMWl3Kg= github.com/caarlos0/env/v11 v11.2.2/go.mod h1:JBfcdeQiBoI3Zh1QRAWfe+tpiNTmDtcCj/hHHHMx0vc= +github.com/caarlos0/env/v11 v11.3.1 h1:cArPWC15hWmEt+gWk7YBi7lEXTXCvpaSdCiZE2X5mCA= +github.com/caarlos0/env/v11 v11.3.1/go.mod h1:qupehSf/Y0TUTsxKywqRt/vJjN5nz6vauiYEUUr8P4U= github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c= github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM= github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4= github.com/stretchr/testify v1.9.0 h1:HtqpIVDClZ4nwg75+f6Lvsy/wHu+3BoSGCbBAcpTsTg= github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY= +github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U= +github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U= gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM= gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA= From 37dea43a96672dbd321d5843c9961e2a8a607456 Mon Sep 17 00:00:00 2001 From: Yusef Mohamadi Date: Thu, 25 Dec 2025 23:43:06 +0100 Subject: [PATCH 2/3] fix gh action golinter --- .github/workflows/ci.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 3e9748b..5acc96c 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -18,7 +18,7 @@ jobs: with: fetch-depth: 0 - name: Linter - uses: golangci/golangci-lint-action@v6.1.0 + uses: golangci/golangci-lint-action@v9.2.0 tests: name: Tests needs: lint From a95652af6228d554ade7ae4d5942a2ba39fc6a28 Mon Sep 17 00:00:00 2001 From: Yusef Mohamadi Date: Thu, 25 Dec 2025 23:43:49 +0100 Subject: [PATCH 3/3] fix gh action golinter --- .golangci.bck.yaml | 43 +++++++++++++++++++++++++++ .golangci.yaml | 74 +++++++++++++++++++++++++++------------------- 2 files changed, 87 insertions(+), 30 deletions(-) create mode 100644 .golangci.bck.yaml diff --git a/.golangci.bck.yaml b/.golangci.bck.yaml new file mode 100644 index 0000000..73eca13 --- /dev/null +++ b/.golangci.bck.yaml @@ -0,0 +1,43 @@ +run: + deadline: 5m + issues-exit-code: 1 + +output: + formats: colored-line-number + print-issued-lines: true + print-linter-name: true + +linters-settings: + dupl: + threshold: 250 + lll: + line-length: 160 + goconst: + min-len: 2 + min-occurrences: 3 + errcheck: + exclude-functions: + - (io.Closer).Close + cyclop: + max-complexity: 10 + funlen: + lines: 50 + +linters: + disable-all: true + enable: + - dupl + - errcheck + - goconst + - gosec + - gosimple + - govet + - ineffassign + - staticcheck + - typecheck + - unused + - funlen + - cyclop + - lll + - forbidigo + diff --git a/.golangci.yaml b/.golangci.yaml index 73eca13..c378fae 100644 --- a/.golangci.yaml +++ b/.golangci.yaml @@ -1,43 +1,57 @@ +version: "2" run: - deadline: 5m issues-exit-code: 1 - output: - formats: colored-line-number - print-issued-lines: true - print-linter-name: true - -linters-settings: - dupl: - threshold: 250 - lll: - line-length: 160 - goconst: - min-len: 2 - min-occurrences: 3 - errcheck: - exclude-functions: - - (io.Closer).Close - cyclop: - max-complexity: 10 - funlen: - lines: 50 - + formats: + text: + path: stdout + print-linter-name: true + print-issued-lines: true linters: - disable-all: true + default: none enable: + - cyclop - dupl - errcheck + - forbidigo + - funlen - goconst - gosec - - gosimple - govet - ineffassign + - lll - staticcheck - - typecheck - unused - - funlen - - cyclop - - lll - - forbidigo - + settings: + cyclop: + max-complexity: 10 + dupl: + threshold: 250 + errcheck: + exclude-functions: + - (io.Closer).Close + funlen: + lines: 50 + goconst: + min-len: 2 + min-occurrences: 3 + lll: + line-length: 160 + exclusions: + generated: lax + presets: + - comments + - common-false-positives + - legacy + - std-error-handling + paths: + - third_party$ + - builtin$ + - examples$ +formatters: + exclusions: + generated: lax + paths: + - third_party$ + - builtin$ + - examples$