DEV Community: Utkarsh Kr. Singh

Building a Clean YAML Config Parser in Go (Without Viper)

Utkarsh Kr. Singh — Tue, 17 Mar 2026 09:50:27 +0000

Originally published on my blog:
https://utkarshkrsingh.me/blog/building-a-flexible-yaml-config-parser/

So I was working on my project Snag, and like most projects at some point, I had to deal with configuration.

Initially, I thought about using Viper since it is widely adopted in the Go ecosystem. But after looking into it, it felt like overkill for what I needed. I wasn’t dealing with multiple config sources, env overrides, or complex layering. I just needed:

A clean YAML config
Strict parsing (no silent mistakes)
Some flexibility in how users define commands

That last requirement turned out to be the most interesting part.

The Problem: Flexible Command Input

I wanted users to define commands in whichever way felt natural to them.

Some prefer writing commands as a single string:

run: go run main.go

Others prefer a more explicit format:

run:
  - go
  - run
  - main.go

Both are valid. Both are useful.

Instead of forcing one format, I decided to support both.

Struct Design (Keeping It Simple)

The config structure itself is pretty straightforward:

// Root configuration structure
type Config struct {
    Global GlobalConfig `yaml:"global"` // Global settings applied across all rules
    Watch  []Rule       `yaml:"watch"`  // List of watch rules
}

// Global-level configuration
type GlobalConfig struct {
    Debounce string   `yaml:"debounce"` // Delay before triggering actions (e.g., "500ms")
    Ignore   []string `yaml:"ignore"`   // List of directories/files to ignore
}

// Individual watch rule
type Rule struct {
    Name     string            `yaml:"name"`     // Name of the rule (used for identification/logging)
    Patterns []string          `yaml:"patterns"` // File patterns to watch (e.g., **/*.go)
    Run      Command           `yaml:"run"`      // Command to execute (custom type)
    Restart  bool              `yaml:"restart"`  // Whether to restart process on change
    Env      map[string]string `yaml:"env"`      // Environment variables for the command
}

Nothing fancy here. The interesting part is the Run field.

Why a Custom Type for Command?

If we used a plain []string, this would fail:

run: go run main.go

Because YAML cannot automatically convert a string into a slice.

So instead, I introduced a custom type:

// Command represents a shell command split into arguments
type Command []string

This allows us to define exactly how YAML values should be interpreted.

Custom Unmarshalling (The Core Idea)

func (c *Command) UnmarshalYAML(value *yaml.Node) error {
    switch value.Kind {

    // Case 1: Command provided as a single string
    case yaml.ScalarNode:
        // Split the string into arguments like a shell would
        args, err := shlex.Split(value.Value)
        if err != nil {
            return err
        }

        // Assign parsed arguments to Command
        *c = args

    // Case 2: Command provided as a list
    case yaml.SequenceNode:
        var arr []string

        // Decode YAML sequence directly into []string
        if err := value.Decode(&arr); err != nil {
            return err
        }

        *c = arr

    // Any other type is invalid
    default:
        return fmt.Errorf("invalid type for run: expected string or list")
    }

    return nil
}

This is where the flexibility comes from:

If the YAML value is a string, we split it into arguments
If it is already a list, we use it directly

The key detail here is using shlex.Split instead of strings.Split.

It correctly handles things like:

run: go run "main file.go"

Which becomes:

[]string{"go", "run", "main file.go"}

Defaults: Small Feature, Big Impact

A config system should not force users to define every single field.

func (c *Config) ApplyDefaults() {
    // If debounce is not provided, use a sensible default
    if c.Global.Debounce == "" {
        c.Global.Debounce = "500ms"
    }
}

This keeps things user-friendly while still giving control when needed.

Validation: Where Most Bugs Are Prevented

Parsing only tells you that the YAML is valid. It does not tell you if it is correct.

That is where validation comes in.

func (c *Config) Validate() error {

    // Ensure at least one watch rule is defined
    if len(c.Watch) == 0 {
        return errors.New("no watch rules defined")
    }

    // Validate debounce duration format
    if c.Global.Debounce != "" {
        if _, err := time.ParseDuration(c.Global.Debounce); err != nil {
            return fmt.Errorf("invalid debounce: %w", err)
        }
    }

    // Validate each rule
    for i, rule := range c.Watch {

        // Rule must have a name
        if strings.TrimSpace(rule.Name) == "" {
            return fmt.Errorf("rule at index %d is missing a name", i)
        }

        // Rule must define at least one pattern
        if len(rule.Patterns) == 0 {
            return fmt.Errorf("rule '%s' must have at least one pattern", rule.Name)
        }

        // Rule must define a command to run
        if len(rule.Run) == 0 {
            return fmt.Errorf("rule '%s' is missing a run command", rule.Name)
        }
    }

    return nil
}

This ensures:

Required fields are present
Values are valid (like duration parsing)
Errors are caught early with clear messages

Strict YAML Parsing (Highly Recommended)

decoder.KnownFields(true) // Reject unknown fields instead of ignoring them

This enables strict mode.

If a user writes:

debouce: 500ms

Instead of silently ignoring it, the parser throws an error.

Loading Flow (Putting Everything Together)

func (cfgMgr *ConfigMgr) Load() error {

    // Read config file from disk
    data, err := os.ReadFile(cfgMgr.FilePath)
    if err != nil {
        return err
    }

    // Create YAML decoder
    decoder := yaml.NewDecoder(bytes.NewReader(data))

    // Enable strict field checking
    decoder.KnownFields(true)

    // Decode YAML into struct
    if err := decoder.Decode(&cfgMgr.Config); err != nil {
        return fmt.Errorf("invalid yaml format: %w", err)
    }

    // Apply default values for missing fields
    cfgMgr.Config.ApplyDefaults()

    // Validate the final configuration
    if err := cfgMgr.Config.Validate(); err != nil {
        return fmt.Errorf("configuration validation failed: %w", err)
    }

    return nil
}

The flow is intentionally simple:

Read file
Decode YAML
Apply defaults
Validate

Example Configuration

global:
    debounce: 500ms
    ignore:
        - .git
        - vendor
        - node_modules

watch:
    - name: server
      patterns:
          - "**/*.go"
      restart: true
      run: go run main.go
      env:
          PORT: "8080"
          ENV: development

Debugging Tip: Print the Final Config

data, _ := json.MarshalIndent(cfgMgr.Config, "", "    ")
fmt.Println(string(data))

This helps verify that parsing, defaults, and transformations are working correctly.

What This Approach Gets Right

After building this, a few things stood out:

You do not always need a heavy library like Viper
Custom unmarshalling gives you precise control
Supporting flexible input formats improves usability
Defaults and validation make the system robust
Strict parsing prevents subtle configuration bugs

Final Thoughts

For tools like Snag, this approach hits a good balance between simplicity and control.

It avoids unnecessary abstraction while still being flexible and safe.

If your configuration needs are similar—single file, predictable structure, and a bit of flexibility—using yaml.v3 directly is a solid choice.

Building a Recursive File Watcher in Go using fsnotify

Utkarsh Kr. Singh — Sun, 15 Mar 2026 18:07:51 +0000

Originally published on my blog:
https://utkarshkrsingh.me/blog/recursive-file-watching-golang-fsnotify/

In my previous blog, I talked about my project Snag and discussed questions like:

What am I going to change?
What features am I planning to implement?
How can I make the system scalable, testable, and maintainable?

But one important question naturally comes up:

“Hey Utkarsh, how are you going to detect file creation, modification, or deletion inside a directory?”

The answer lies in how the operating system handles filesystem events.

For example, Linux provides a subsystem called inotify which allows programs to monitor filesystem events such as:

File creation
File modification
File deletion
Directory changes

To interact with this subsystem in Go, we can use the package fsnotify.

fsnotify provides a simple and cross-platform way to watch filesystem events in Go.

In this article, we will build a recursive file watcher in Go using fsnotify.

Prerequisites

To follow along with this tutorial, you should have:

Basic knowledge of Go
Understanding of goroutines and channels
Familiarity with filesystem structures

Install the dependency:

go get github.com/fsnotify/fsnotify

Why Recursive Watching?

One limitation of fsnotify is that it does not watch directories recursively.

This means if you only watch the root directory:

project/
 ├── main.go
 ├── config/
 │   └── config.yaml
 └── handlers/
     └── user.go

Only changes in project/ will trigger events.

Changes inside:

config/
handlers/

will not be detected unless watchers are explicitly added to those directories.

Because of this, we must:

Recursively find all directories
Register watchers on each directory

That is exactly what we will implement.

Implementation

1. Collect All Directories Recursively

The first step is to gather all directories inside the project.

Since fsnotify does not support recursive watching by default, we must manually collect all directories and register them.

We will create a function called getAllDirs.

// getAllDirs recursively walks the filesystem starting
// from the given root directory and returns all directories.
// This is needed because fsnotify does not watch directories
// recursively by default.
func getAllDirs(root string) ([]string, error) {
    var dirs []string

    err := filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error {
        if err != nil {
            fmt.Printf("Error accessing path %s: %v\n", root, err)
            return nil
        }

        // Collect directories only
        if d.IsDir() {
            dirs = append(dirs, path)
        }

        return nil
    })

    if err != nil {
        return nil, err
    }

    return dirs, nil
}

This function walks the entire directory tree and returns a slice containing all directories.

2. Start the File Watcher

Next, we create a function called startWatching which:

Creates a watcher
Registers directories
Listens for filesystem events

// lastEvent keeps track of the last time we processed
// an event for a specific file. This helps prevent
// duplicate events that can occur in rapid succession.
var lastEvent = make(map[string]time.Time)

// startWatching starts a filesystem watcher on the
// provided directories and listens for file events.
func startWatching(dirs []string) {
    watcher, err := fsnotify.NewWatcher()
    if err != nil {
        log.Fatal(err)
    }
    defer watcher.Close()

    // Goroutine that listens for filesystem events
    go func() {
        for {
            select {

            // File system events
            case event, ok := <-watcher.Events:
                if !ok {
                    return
                }

                // Ignore permission change events
                if event.Has(fsnotify.Chmod) {
                    continue
                }

                // Ignore temporary files (like editor backups)
                if strings.HasSuffix(event.Name, "~") {
                    continue
                }

                // Debounce events that fire too quickly
                now := time.Now()
                if t, exists := lastEvent[event.Name]; exists {
                    if now.Sub(t) < 500*time.Microsecond {
                        continue
                    }
                }
                lastEvent[event.Name] = now

                // Handle file/directory creation
                if event.Has(fsnotify.Create) {
                    isDir, err := isDirectory(event.Name)
                    if err != nil {
                        log.Fatal(err)
                    }

                    if isDir {
                        log.Println("Add watcher dynamically to new directory:", event.Name)
                    } else {
                        log.Println("Run configured command for file:", event.Name)
                    }
                }

                // Handle file modifications
                if event.Has(fsnotify.Write) {
                    log.Println("Modified file:", event.Name)
                }

            // Error handling
            case err, ok := <-watcher.Errors:
                if !ok {
                    return
                }
                log.Println("Watcher error:", err)
            }
        }
    }()

    // Register watchers for all provided directories
    for _, dir := range dirs {
        err = watcher.Add(dir)
        if err != nil {
            log.Fatal(err)
        }
    }

    // Block forever to keep the program running
    <-make(chan struct{})
}

What this function does

Creates a filesystem watcher
Listens for events inside a goroutine
Filters unnecessary events
Handles file creation and modification
Uses debouncing to avoid duplicate triggers

3. Detect Whether the Event is a File or Directory

When a Create event occurs, we need to determine whether the created entity is a file or directory.

// isDirectory checks whether the provided path
// refers to a directory.
func isDirectory(path string) (bool, error) {
    info, err := os.Stat(path)
    if err != nil {
        return false, err
    }

    return info.IsDir(), nil
}

This function simply checks filesystem metadata to determine if the path is a directory.

4. Program Entry Point

Finally, everything comes together in the main function.

// Entry point of the program.
// It gathers all directories starting from the root
// and starts the filesystem watcher.
func main() {
    root := "."

    // Collect all directories recursively
    dirs, err := getAllDirs(root)
    if err != nil {
        log.Fatalf("Failed to get directories: %v\n", err)
    }

    // Start watching filesystem changes
    startWatching(dirs)
}

Step-by-step flow

Start from the root directory
Recursively collect all directories
Register watchers for each directory
Listen for filesystem events

How the Watcher Works

The overall workflow looks like this:

Project Directory
        ↓
Scan All Directories
        ↓
Register Watchers
        ↓
Listen for Events
        ↓
Filter / Debounce Events
        ↓
Trigger Action

This pipeline allows us to efficiently monitor filesystem changes across the entire project.

Final Result

With this approach, we have built a recursive file watcher system.

The program can:

Watch a directory
Monitor all subdirectories
Detect file creation and modification events
Filter unnecessary filesystem noise
Prevent duplicate triggers

This structure can serve as the foundation for tools like:

Hot reload systems
Build automation tools
File synchronization utilities
Developer productivity tools

You can extend this watcher to trigger commands, run tests, reload servers, or automate workflows whenever files change in your project.

Snag - Rewrite

Utkarsh Kr. Singh — Wed, 11 Mar 2026 09:59:43 +0000

Originally published on my website:
https://utkarshkrsingh.me/blog/snag-rewrite/

In the early days when I started learning Go, I wasn't very familiar with its idioms. Like most beginners, I experimented by building small projects. One of those projects was Snag.

The idea behind Snag was simple: it watched the current directory and checked whether a file had been modified. If a change was detected, it would automatically compile the code.

However, there was a major limitation. The compile commands were hard-coded directly into the source code. This made the tool impractical and limited it to only a few languages such as C/C++, Python, and Go. Because of this design choice, the project had several issues and wasn't an ideal implementation.

At that time I also wasn't familiar with GitHub, so the project never made it there.

Now things are different. I have spent much more time working with Go, learning its idioms, and understanding how to write more idiomatic and maintainable code. Because of that, I decided to rewrite the project from scratch.

So welcome to my blog on Snag — Rewrite, where I will discuss the improvements and design decisions I plan to implement in the new version.

Old Snag Abilities

The original version of Snag did not have many features. Its primary responsibility was simple: detect file modifications and react accordingly.

But this raises an interesting question:

How does Snag detect file changes?

To understand this, we need to look at how Linux tracks file and directory updates.

Linux provides a subsystem called inotify, which monitors filesystem events such as file creation, modification, and deletion. Tools and applications can subscribe to these events to react whenever something changes in the filesystem.

In the Go implementation, I used the package fsnotify.

This library internally uses the inotify API on Linux to watch filesystem events. With it, Snag was able to detect when files were modified and trigger the appropriate action.

Now let's look at what I plan to improve in the new version.

My Plans for the New Version

For the rewrite, I want to make the project more flexible, testable, and scalable. Here are the main ideas I plan to implement.

1. Decoupling Configuration from Logic

In the previous version, build commands were hard-coded in the source code. This made the tool rigid and difficult to adapt for different projects.

In the rewrite, I plan to introduce a configuration file. This file will allow users to specify:

Files or directories to ignore
Commands to run when files change
Other project-specific behavior

You can think of it as something similar to a Makefile. The difference is that instead of manually running commands, Snag will automatically trigger them when relevant files are modified.

This allows developers to focus on writing code rather than repeatedly running build commands.

2. Concurrency and Context

This time I want to take advantage of one of Go’s strongest features: concurrency.

I plan to run commands using goroutines so that processes can execute independently. At the same time, I will manage these processes using context.

This approach solves an important problem.

Imagine a file changes while the previous build process is still running. Instead of tracking PIDs (process IDs) manually, I can simply cancel the running task using the context. Once the previous process is cancelled, a new one can start immediately.

This makes the system cleaner and avoids the complexity of manual process management.

3. Recursive Watching

Another improvement will be recursive directory watching.

At startup, Snag will walk through the entire directory tree and attach watchers to all subdirectories. Additionally, if a new directory is created while the program is running, a watcher will be added dynamically.

This ensures that changes anywhere in the project are detected automatically.

Final Thoughts

These are the core ideas behind the rewrite of Snag. My goal is to turn it into a more robust and flexible tool.

You can think of Snag as a language-agnostic hot reloader. Instead of being tied to a specific language, it relies on its configuration file to determine what files to watch and what commands to execute.

Hopefully, this rewrite will not only improve the tool but also make it a solid project to showcase on my resume.

CORS - Cross Origin Resource Sharing

Utkarsh Kr. Singh — Wed, 10 Dec 2025 17:39:56 +0000

CORS is one of those things you don’t really learn…

You just run into it.

Everything works.

API is up.

Backend is responding.

Then the browser says:

“Blocked by CORS policy.”

And suddenly you’re questioning your life choices 😄

For a long time, CORS feels like a bug.

But it’s not.

It’s actually the browser trying to protect users by saying:

“Hey, are you sure this website should be talking to that server?”

That’s why:

It works in Postman but not in the browser
The backend logs look fine
Adding one missing header magically fixes everything

And also why “just disable CORS” is a terrible idea

(even though we’ve all Googled it).

Why Postman and curl don’t care about CORS

CORS is a browser-only security rule.

Postman, curl, and other tools aren’t trying to protect end users—they’re just clients making HTTP requests. They don’t block responses based on origin, so they’ll happily show you the data even if the server never sends CORS headers.

Browsers, on the other hand, sit between your app and the user. If they didn’t enforce CORS, any website could silently read data from another site using your logged-in session.

That’s the real threat CORS is preventing.

And what’s a preflight request?

That mysterious OPTIONS call you see before your actual API request?

That’s the browser asking politely first.

Before sending certain requests (like PUT, DELETE, or requests with custom headers), the browser sends a preflight request to the server saying:

“Hey, I want to make this request with these methods and headers. Are you okay with that?”

If the server says yes (with the right CORS headers), the real request is sent.

If not, the browser stops everything right there.

Once it clicks, CORS stops being scary.

You realize it’s just rules about who can talk to whom, and how explicitly you need to say yes.

Honestly, understanding CORS felt like a small rite of passage as a developer.

If CORS has ever ruined your day, welcome to the club.

If you’ve mastered it, you’ve earned your badge.

What was your first CORS error like? 👇

🚀 From Clueless to Confident: My First Week with Keploy for API Testing

Utkarsh Kr. Singh — Fri, 27 Jun 2025 07:06:36 +0000

I’ll be honest—I had zero experience with proper API testing until just recently. Sure, I’ve built a few APIs here and there using Go and knew how to check responses in Postman or curl. But writing tests? Especially integration or E2E ones? I always meant to do it... but never really did. Mostly because it felt tedious, confusing, and well, manual.

That changed this week when I stumbled upon Keploy—an AI-powered API testing tool—and I decided to try it out for a workshop project. Here's what happened 👇

🤯 My Usual API Testing (Or Lack of It)

Before Keploy, my “testing strategy” was mostly just:

Run the backend.
Hit endpoints manually using Postman.
Check console logs or database rows to “see if it worked”.

That obviously didn’t scale, and I knew it wasn’t the right way to test things—but setting up full test suites (mocking, database seeding, etc.) felt like a huge barrier. Plus, every time the API changed, I’d have to go update a bunch of test cases by hand. 😵‍💫

💡 First Time Using Keploy

Keploy promised “automated test generation” just by using my app normally. Skeptical but curious, I decided to give it a shot:

I ran my backend app (a simple anime watchlist built in Go).
Installed the Keploy CLI and attached it to my app.
Used the app like a real user—adding, updating, deleting anime records.
Keploy silently recorded all the API calls and generated test cases and mocks from real traffic!

No writing test functions. No crafting request/response payloads. No environment setup nightmares.

⚙️ Running the Tests

I then ran keploy test—and to my surprise, it spun up the same traffic I had recorded, validated the responses and even simulated the same DB behavior.

What blew me away was the coverage: I basically hit a few endpoints, and Keploy had already generated 70–80% test coverage just from that. I wasn’t even trying!

With a few more user interactions, I pushed it to nearly 100%.

😅 What Was Hard

Of course, it wasn’t completely smooth:

Getting Keploy to authenticate with the cloud dashboard took a few tries (pro tip: you need a valid API key from Keploy’s dashboard).
My app uses Docker-based databases, so I had to configure ports and ensure both read/write databases were accessible.
Since I was new to this, understanding what was going on “under the hood” took some reading.

But compared to writing tests manually from scratch? This was 10x easier.

✨ What Excites Me Now

Confidence in my APIs: Every time I make changes, I can rerun the suite and trust that it’ll catch regressions.
Speed: Recording tests while I just use the app is wild. I’m not wasting hours writing repetitive assertions.
Scalability: If I work on a bigger team, everyone benefits from shared test coverage without needing every dev to be a testing expert.

🧠 Final Thoughts (From a Beginner)

I’m still new to API testing, but Keploy made it feel like I wasn’t. It feels more like having a smart assistant watching over your app and creating tests for you, rather than something you need to fight with.

If you’re like me—someone who avoided testing because it felt like a chore—give Keploy a shot. You’ll go from 0 to hero faster than you think.