Forem: Asoseil

From chaos to signal: Taming high-frequency OS events

Asoseil — Tue, 20 Jan 2026 15:14:55 +0000

If you have ever built a hot-reloader, a build tool, or a file sync agent in Go using raw fsnotify or syscall events, you have definitely encountered the "double-fire" problem.

You save a file once.
Your terminal goes wild:

EVENT: "/src/main.go" [CHMOD]
EVENT: "/src/main.go" [RENAME]
EVENT: "/src/main.go" [WRITE]
EVENT: "/src/main.go" [WRITE]

Your build triggers four times, your CPU spikes, logs scroll too fast to be read, and it's really frustrating.

This isn't a bug in the code; it isn't even a bug in the library; it is fundamentally how operating systems work. But for a developer experience tool, "technically correct" feels broken.

In this article, I will show you how I fixed this behaviour in sgtdi/fswatcher using Debouncing and Smart filtering, so you can build tools that feel instant and solid.

Raw events vs. User intent

Operating systems don't care about your "Save" intent. They report atomic file system operations, and when you hit Ctrl+S in your IDE, the editor doesn't just open the file and write bytes, cause to ensure data safety, it often performs a "Safe Write" dance:

Create a temporary file
Write content to the temporary file
Delete the original file
Rename the temp file to the original name
Chmod to restore permissions

To the OS, this looks like a flurry of creation, deletion, renaming, and attribute modification events, but to the final user, it's just one "Save".

If your application reacts to every single one of these events, you are wasting resources. Worse, you might try to read the file in the nanoseconds between the "Delete" and the "Rename", causing your build tool to crash with a file not found error.

Event Merging and Throttling

I want my tools to be snappy and waiting for a "quiet period" (trailing edge debouncing) introduces lag. Instead, sgtdi/fswatcher uses a Leading edge approach with event merging.

The debouncer acts as a gatekeeper; it groups events by Path and ensures that it can act immediately on the first sign of activity, suppressing the subsequent "echoes" caused by the OS.

The engine room

Here is how I implemented this in sgtdi/fswatcher. The secret sauce is the debouncer struct, which maintains a short-term memory of file activity.

I use a map called lastSeen to track the most recent event for every file path. This allows me to throttle events on a per-file basis—so a busy log file doesn't block the rest of the project. A sync.Mutex is essential here because file system events arrive concurrently from multiple goroutines.

type debouncer struct {
    lastSeen map[string]WatchEvent
    cooldown time.Duration
    mu       sync.Mutex
}

The logic for deciding whether to emit an event lives in ShouldProcess. When a new event arrives, I lock the mutex to ensure safety.

I check lastSeen to see if this file has been active recently. If I find an existing entry and the new event arrived within the cooldown window, I treat it as "noise" or an OS echo. Instead of emitting it, I merge it into the previous event (combining flags like Write + Chmod) and suppress it.

If the file is new or the cooldown has expired, I update the record and let the event pass through immediately. This ensures the user sees the result of their action instantly.

func (d *debouncer) ShouldProcess(ev WatchEvent) (WatchEvent, bool) {
    d.mu.Lock()
    defer d.mu.Unlock()

    last, exists := d.lastSeen[ev.Path]
    if exists {
        if time.Since(last.Time) < d.cooldown {
            merged := mergeEvents(last, ev)
            d.lastSeen[ev.Path] = merged
            return merged, false 
        }
    }

    d.lastSeen[ev.Path] = ev
    return ev, true
}

This simple pattern is incredibly powerful cause It converts the chaotic stream of OS noise into a singular, meaningful signal.

Using it in FSWatcher

When you initialize the library, you just pass the WithCooldown option and the library handles the concurrency complexity for you.

w, _ := fswatcher.New(
    fswatcher.WithPath("./src"),
    fswatcher.WithCooldown(100 * time.Millisecond), // The magic number
)

Now, that flurry of 4-5 events becomes exactly one EventMod (Modify) event.

Ignoring the noise with smart filtering

Debouncing handles duplicate events, but what about useless ones?

If you are watching a project root, you rarely want to trigger a rebuild when:

.git/ internal files change (index, HEAD updates).
node_modules gets updated by npm install.
OS junk files like .DS_Store or thumbs.db appear.
Your own build output directory (e.g., dist/ or bin/) changes.

A naive watcher forces you to write a giant if statement in your main event loop:

// The "Naive" Approach
for event := range watcher.Events {
    if strings.Contains(event.Name, ".git") { continue }
    if strings.Contains(event.Name, "node_modules") { continue }
    if strings.HasSuffix(event.Name, ".DS_Store") { continue }

    // finally process...
}

This is tedious and error-prone.

Platform-wware filtering

To solve this elegantly, I need to respect platform conventions.

First, let's handle System Artifacts. Your OS leaves breadcrumbs everywhere—files like .DS_Store on macOS, or .swp files from text editors. By maintaining a list of these known prefixes and suffixes, I can identify and discard them before they ever reach your logic.

// platform_darwin.go
var osPrefixes = []string{"~", "._"}
var osSuffixes = []string{".DS_Store", ".swp"}

func isSystemFile(path string) bool {
    base := filepath.Base(path)

    for _, p := range osPrefixes {
        if strings.HasPrefix(base, p) { return true }
    }
    for _, s := range osSuffixes {
        if strings.HasSuffix(base, s) { return true }
    }
    return false
}

Next, I handle Hidden Files. In the Unix tradition, any file or directory starting with a dot . is considered hidden. These often contain configuration or version control data (like .git) that you typically want to ignore by default.

func isHidden(path string) bool {
    return strings.HasPrefix(filepath.Base(path), ".")
}

The `fswatcher` approach

sgtdi/fswatcher splits the responsibility to keep configuration clean:

System Filters: The library automatically handles the OS noise using the logic above. You don't need to configure it; it just works.
Regex Filters: I leave the project-specific choices to you. Since generic hidden files (like .git) are not auto-excluded (you might want to watch them!), you use WithExcRegex to define what matters for your specific project.

w, _ := fswatcher.New(
    fswatcher.WithPath("."),
    // Exclude .git (hidden files aren't auto-ignored) and build artifacts
    fswatcher.WithExcRegex(".*\\.git.*", ".*node_modules.*", ".*dist.*"),
    // Only explicitly include source files
    fswatcher.WithIncRegex(".*\\.go$", ".*\\.html$"), 
)

This approach gives you a clean stream of events that actually represent user changes, not system noise.

Handling raw file system events is a trap. It leads to buggy, resource-intensive tools that frustrate users. By decoupling the OS event (what happened technically) from the User intent (what changed meaningfully), we can build tools that feel snappy, responsive, and polished.

The combination of smart event throttling and robust regex filtering transforms a chaotic stream of system calls into a clean stream of actionable events.

Check out the full implementation and try it in your next Go project: sgtdi/fswatcher

Stop Hitting CTRL+C: The way to hot reload Go apps

Asoseil — Thu, 04 Dec 2025 08:13:48 +0000

We need to talk about the "Micro-Interruption" and what it actually does to your brain during an intense coding session.

You know the specific feeling I am talking about:

You are deep in the code mines, mentally holding a complex dependency graph in your head, and you finally implement the fix for a race condition.
You hit Cmd+S to save, and then the administrative ritual begins.
You have to physically shift your focus from your code editor to your terminal window, breaking your visual focus.
You have to press Ctrl+C to send a kill signal to your running server and wait a split second for the socket to close.
You press the Up Arrow to recall your run command, and finally, you hit Enter.

It seems like a trivial action that takes only a few seconds, but when you perform it hundreds of times a day, the cumulative effect is devastating.

It is not just the time lost; it is the destruction of your "Flow State"

Every single time you interact with the terminal to do administrative work, your brain drops a tiny piece of the complex logic you were holding.
By the time the server/app restarts and you look back at your code, you have to spend mental energy "reloading" your own internal state, slowing down your momentum significantly.

Make the tooling invisible

To improve my daily development workflow, I built Vai cause I was exhausted from fighting my terminal and wanted a "save and see" experience that felt native to the Go ecosystem.

It is a zero-dependency, zero-configuration CLI tool that handles the restart cycle for you automatically, effectively removing the barrier between writing code and seeing the results of that code. It respects the Go philosophy of simplicity: a single binary that does one thing well.

Unlike polling-based watchers that eat your battery with polling, it uses native OS filesystem events to react instantly with fswatcher, another low-level library that I recently published.

Zero Config, instant feedback

The beauty of the tool lies in its absolute simplicity and lack of friction. If your standard workflow involves running your application with go run ., you do not need to change your project structure, add a config file, or learn a new set of flags.

Prefix your command with Vai, and instead of the manual cycle of stopping and starting, you transition to a "fire and forget" mode.

That is the extent of the onboarding process. From that moment on, Vai takes over the tedious process management loop. It monitors your .go files, your go.mod, and your go.sum recursively with intelligent defaults, automatically ignoring hidden directories like .git or vendor folders.

Here is what the immediate transition looks like in your daily workflow:

# ❌ The Old Way (The "Muscle Memory" Trap)
# 1. Run the app
$ go run cmd/server/main.go
# 2. Switch to editor, make changes, save
# 3. Switch to terminal
# 4. Hit CTRL+C to kill the process
# 5. Hit Up Arrow, then Enter to restart
# 6. Repeat 100x a day

# ✅ The New Way (The "Flow State" Method)
# 1. Run this once in the morning
$ vai go run cmd/server/main.go
# 2. Never touch the terminal again

If you are doing Test Driven Development, you can have Vai re-run your test suite every time you save a file, giving you immediate red/green feedback without lifting a finger.

# The standard way (boring and manual):
$ go test -v ./...

# The TDD way (instant and automated):
$ vai go test -v ./...

Using the CLI mode, we can construct a "one-liner" more advanced that acts as a complete development environment. There is support for command chaining, environment injection, and regex filtering all at once.

vai \
  --path="./services/billing" \
  --regex=".*\\.go$" \
  --env="PORT=8081,DB_HOST=localhost,DB_USER=postgres" \
  --cmd "go fmt ./services/billing/..." \
  --cmd "go vet ./services/billing/..." \
  --cmd "go run ./services/billing/cmd/server"

Advanced workflow

The CLI is powerful, but typing that command every day is tedious, and sharing it with a team is difficult. For complex, reproducible workflows, there is support for a customizable vai YAML file.

Let's imagine a scenario where you are building a Go web application that serves HTML templates. You have a split requirement:

Backend Code (.go): Needs to trigger a recompile and restart.
Frontend Templates (.html): Should also restart the server (to reload templates), but you don't need to run Go linters on HTML files.
Test Files (_test.go): Should never restart the server. Instead, they should run the test suite in parallel with the server to ensure you haven't broken anything.

config:
  path: .
  logLevel: info

jobs:
  # Triggers on Go files
  backend-dev:
    on:
      regex: 
        - ".*\\.go$"
        - "!.*_test.go$" # Explicitly exclude tests
    series:
      - cmd: "golangci-lint run"
      - cmd: "go build -o ./tmp/app ."
      - cmd: "./tmp/app"

  # Template Reloader
  frontend-reload:
    on:
      regex: 
        - ".*\\.html$"
    series:
      - cmd: "./tmp/app"

  # Parallel test runner
  test-runner:
    on:
      regex: 
        - ".*_test\\.go$"
    parallel:
      - cmd: "go test -v ./..."
      - cmd: "govulncheck ./..."

Whether you are running a quick one-off script with the CLI or orchestrating a complex microservices architecture with a vai.yml, the goal remains the same: remove the friction between your thought process and the running code.

Resources

Golang Vai
Fswatcher

Linux, macOS, and Windows broke my code, so I built a cross-platform test strategy

Asoseil — Fri, 21 Nov 2025 19:37:10 +0000

Cross-platform filesystem events sound simple in theory:

make a file change, receive a notification

In practice, three operating systems interpret, buffer, group, and deliver those notifications in completely different ways. The same action can trigger a single clean event on one platform, several intermediate ones on another, or a delayed burst somewhere else. Getting consistent behaviour across all of them becomes surprisingly fragile, especially when concurrency and real-world workloads enter the picture.

I ran into all of this while building FSWatcher, a file-watching component that needed to behave consistently on every platform. Under the hood it uses FSEvents on macOS, inotify on Linux, and ReadDirectoryChangesW on Windows, so it ended up exposing all the differences between the three systems at once. Once concurrency entered the picture, those differences became even more noticeable, and many assumptions I had initially made didn’t hold up.

Correctness on one platform didn’t imply correctness on another, and correctness under light load didn’t tell me much about behaviour under stress. The test strategy had to become more deliberate, more platform-aware, and more concurrency-resistant. The result is a pipeline that consistently exposes cross-platform issues early and keeps the watcher stable across all three environments.

Cross-Platform behaviour is more different than you expect

All three operating systems surface events in their own way. macOS sometimes groups directory-level changes; Linux produces multiple events for what conceptually feels like “one change”; Windows often emits cleaner, consolidated notifications.

Any assumption about ordering, timing, or granularity breaks immediately.

For example, writing three files in sequence rarely produces events in that same order. Under heavy I/O, events can arrive seconds apart or all at once. This means tests can’t focus on sequences, they have to focus on eventual consistency and presence of the expected state transitions.

FSWatcher also supports runtime path addition and removal, and this affects the testing model: the suite needs to confirm that paths being watched dynamically start emitting events immediately, and removed paths truly stop. This pushes the tests into scenarios where the watcher has to respond to concurrent updates to its own internal structures.

CI setup that doesn’t hide platform behaviours

The current CI pipeline runs the full suite on macOS (Intel and ARM), Linux, and Windows. It’s intentionally configured not to stop early, because a Windows-only failure is still valuable even if Linux is green.

strategy:
  fail-fast: false
  matrix:
    include:
      - os: macos-26
      - os: macos-latest
      - os: ubuntu-latest
      - os: windows-latest

The Go race detector runs on macOS and Linux and is responsible for catching most of the logic bugs that would otherwise appear as rare, intermittent failures. It has already flagged unsynchronised map writes, channel close races, and struct fields being read while another goroutine was updating them. These are the sorts of concurrency defects that aren’t visible in code review and rarely reproduce manually.

Windows builds skip -race but still run the full suite, which is important because Windows has its own timing behaviours and handles resources differently than Unix-like systems.

A periodic C*odeQL analysis also runs to flag suspicious patterns* and unsafe syscall usage. Even though it isn’t concurrency-specific, it helps ensure that filesystem and OS interactions aren’t quietly failing.

Testing strategy cross-platform

The tests had to change significantly to become stable. The early versions relied on fixed sleeps and assumptions about order. Replacing those with event-driven constructs made the suite consistent across runners.

A readiness channel ensures that the watcher is fully started before operations begin:

select {
case <-readyChan:
case <-time.After(5 * time.Second):
    t.Fatal("Watcher is not ready")
}

Event collection runs concurrently in its own goroutine, which reflects how the watcher behaves in practice. The use of mutex-protected slices keeps the test deterministic without relying on sleep.

One of the most important pieces is the randomized workload generator:

expected := performOperations(t, tempDir, 1000)

performOperations performs a mix of file creation, modification, rename, directory creation, deletion, and nested deletion

Because the operations are randomized, each run produces different event patterns, and this forces the watcher to handle unpredictable sequences, essentially a built-in form of stress testing.

The correctness check doesn’t compare order. It compares the presence of expected paths:

if !receivedEvents[path] {
    missing = append(missing, path)
}

And the tests ensure the watcher stops cleanly, channels close, and no goroutines outlive the test.

FSWatcher also exposes statistics (processed, dropped, lost events). The tests validate that backpressure logic is correct by filling channels intentionally and verifying that dropped events land in the right place and that lost events are accounted for.

Runtime path addition and removal are tested by creating temporary directories, watching multiple roots, and ensuring that removed paths do not emit events even if files are changed afterward.

All of this results in a suite that goes beyond basic unit testing: it simulates bursty workloads, random event order, dynamic watch roots, and concurrent shutdown, exactly the kind of scenarios that real usage hits over time.

What the current tests cover effectively

Even without formal stress tools or property-based frameworks, the suite already exercises several advanced behaviors:

randomized file operations simulate realistic filesystem churn
concurrent event ingestion tests backpressure and channel behavior
dynamic path addition/removal stresses internal synchronization
multi-platform CI exposes OS-specific timing and ordering issues
shutdown tests verify that goroutines and resources clean up reliably
dropped/lost event tests validate overload behaviour
watchers handle thousands of events generated through random workloads

This places FSWatcher’s test suite closer to a real integration environment rather than a traditional set of unit tests.

Go further

Since many stress-like behaviours are already present thanks to the randomized workload generator, the next improvements should be focused on areas not yet covered by the existing suite.

A few upgrades would extend the reliability of the watcher in scenarios that aren’t currently exercised:

Long-Running endurance tests

Running the watcher for hours rather than seconds helps expose:

slow memory leaks
handle/file-descriptor growth over time
goroutine buildup
timing drift under GC pressure

This could run weekly in CI or manually before releases.

Fault injection with failpoints

Injecting controlled failures into:

syscall returns
event dispatch paths
directory iteration
queue overflows

would reveal whether FSWatcher recovers correctly from partial failures. Randomising delays inside goroutines would also help expose race windows that normal tests rarely hit.

These two additions would meaningfully extend the testing scope without overlapping what the current suite already achieves.

Testing concurrent, cross-platform code requires a strategy that embraces inconsistency rather than fighting it. Different event models, different timing guarantees, and different behaviours under load mean the tests must be adaptive rather than prescriptive.

The combination of multi-platform CI, race detection, randomized workloads, event-driven assertions, and strict cleanup has made FSWatcher stable across all three operating systems. With endurance testing and fault injection added on top, the watcher would be able to withstand even more demanding production scenarios.

When a simple order update breaks Revolut Checkout workflow

Asoseil — Fri, 14 Nov 2025 08:07:32 +0000

During a recent payment gateway integration, i discovered a fundamental design flaw in the Revolut SDK that breaks dynamic checkout flows and forces developers to implement complex workarounds.

The Problem: Static state in a dynamic world

On the web, RevolutCheckout component requires creating a new order via API before rendering the checkout input form. This creates an unusual lifecycle:

Frontend requests backend to create a Revolut order
Backend calls Revolut API and receives an order token
Frontend initializes RevolutCheckout with that token
Payment component renders

This flow has a critical limitation: the checkout component caches the initial order state and never re-synchronizes it with the backend.

When things break

In modern single-page checkout experiences, users frequently modify their orders:

Adjusting quantities
Applying discount codes
Adding or removing items
Updating shipping options

Each change requires updating the order amount on Revolut's backend. While the API supports this via PATCH /api/orders/{order_id}, the checkout component doesn't handle it.

When you update an order after the checkout component has mounted, attempting to complete the payment fails with a generic error:

"Transaction failed. Please contact the merchant to resolve this problem."

Reproduction

Here's a minimal example that demonstrates the issue:

Create an Order

curl -L -X POST 'https://sandbox-merchant.revolut.com/api/orders' \
-H 'Content-Type: application/json' \
-H 'Revolut-Api-Version: 2025-10-16' \
-H 'Authorization: Bearer <key>' \
--data-raw '{"amount": 500, "currency": "EUR"}'

Response:
json{
  "id": "540d94a9-b356-a52f-8870-dabaac383a1b",
  "token": "b140372e-cb3b-47f8-8c7e-b22090ea4ac2",
  "type": "payment",
  "state": "pending",
  "created_at": "2025-11-07T06:41:45.820229Z",
  "updated_at": "2025-11-07T06:41:45.820229Z",
  "amount": 500,
  "currency": "EUR",
  "outstanding_amount": 500
}

Update the Order (after RevolutCheckout is mount)

curl -L -X PATCH 'https://sandbox-merchant.revolut.com/api/orders/{order_id}' \
-H 'Content-Type: application/json' \
-H 'Revolut-Api-Version: 2025-10-16' \
-H 'Authorization: Bearer <key>' \
--data-raw '{"amount": 1000, "currency": "EUR"}'

Response:
json{
  "id": "540d94a9-b356-a52f-8870-dabaac383a1b",
  "token": "b140372e-cb3b-47f8-8c7e-b22090ea4ac2",
  "type": "payment",
  "state": "pending",
  "created_at": "2025-11-07T06:41:45.820229Z",
  "updated_at": "2025-11-07T06:43:21.785741Z",
  "amount": 1000,
  "currency": "EUR",
  "outstanding_amount": 1000
}

The order ID and token remain valid, but the checkout component will fail when attempting to complete the payment.

Root cause analysis

The issue stems from a state synchronization mismatch between client and server:

RevolutCheckout caches the initial order state (including amount) when initialized, and the cached state is never refreshed, even when the order is updated via API.

When the user submits a payment, the component sends the cached amount, Revolut's backend detects the mismatch with the current amount and rejects the payment with a generic error message that provides no clarity about the actual issue.

This is a classic case of assuming immutability on the client side while allowing mutability on the server side.

Workaround

The only solution is to remount the checkout component whenever the order changes. Something like:

async function updateOrder() {
    try {
        // Update order via API
        const order = await updateRevolutOrder(
            accessToken,
            order.orderId
        );
        // Completely reinitialize the checkout components
        if (order && order.token) {
            await initializeCardField();
            await initializeRevolutPay();
        }
    } catch (e) {
        console.error("Error updating Revolut order:", e);
    }
}

This workaround has significant drawbacks and requires remounting if you use both RevolutCheckout for the card field and Revolut Pay:

Poor user experience
Every order update triggers a visible remount cycle, causing the checkout form to disappear and reappear. This creates flickering UI and resets any partial input.
Technical Overhead
Backend logs become cluttered with abandoned order records while additional API calls are triggered for every modification, requiring complex state management to handle remounting logic and creating potential race conditions between user interactions and component lifecycle.
Silent failures
Without discovering this through extensive testing, payments fail with no indication of the actual problem, and users see generic error messages that incorrectly suggest contacting the merchant, eroding trust in the checkout process.
Maintenance burden
Developers must build and maintain logic that should be abstracted within the SDK itself.

What should happen

A robust checkout SDK should handle order updates in one of two ways:

Option 1: Invalidate on update
When an order is updated via API, invalidate the existing token and require a new checkout initialization. Make this explicit in the API response.

Option 2: Auto-refresh state
Before submitting payment, **automatically fetch the latest order state **from the backend to ensure synchronization. This could happen transparently within the SDK.

Either approach would eliminate the need for workarounds and provide clear, predictable behavior.

Other payment gateways

Stripe's approach, for comparison, separates the concepts of PaymentIntent (immutable) and amount confirmation (mutable). You can update amounts before confirmation without breaking the payment flow, and the Elements components handle state synchronization internally.

This isn't an edge case—order updates are a standard feature of e-commerce checkouts. Dynamic pricing, discount codes, quantity adjustments, and real-time calculations are expected in modern applications.

The RevolutCheckout inability to handle these updates gracefully represents a fundamental architectural flaw. It shifts the complexity that should be handled by the payment gateway onto every merchant integration.

For developers considering Revolut: Be aware that implementing dynamic checkout flows requires building significant workaround logic. Test order update scenarios thoroughly before going to production.

For the Revolut team: This issue has been reported with reproducible test cases. A fix would significantly improve developer experience and bring the SDK in line with modern payment gateway expectations.

Github revolut-checkout issue

How macOS, Linux, and Windows detect file changes (and why it's hard to catch them)

Asoseil — Wed, 12 Nov 2025 10:10:36 +0000

File watching seems simple on the surface: "tell me when a file changes" But the reality is three completely different APIs with three fundamentally different philosophies about how computers should monitor file systems.

The three main approaches

I recently spent weeks building FSWatcher, a cross-platform file watcher in Go, and the journey taught me that understanding file watching means understanding how each operating system approaches the problems differently.

🍎 macOS: FSEvents (Directory-first)

Apple's philosophy is to monitor directory trees, rather than individual files.

// You say: "watch /Users/me/fswatcher"
// macOS says: "OK, I'll tell you when ANYTHING in that tree changes"

Pros

Low CPU usage
Efficient for large directories
Event-driven (no polling)

Cons

Gives you directory-level info, not file-level
Can flood you with redundant events
You must filter what you actually care about

Example event

//Event: /Users/me/fswatcher/src changed
// You have to figure out WHAT changed in /src

🐧 Linux: inotify (File-First)

Linux's philosophy: granular control over specific files and directories.

// You say: "watch /home/me/fswatcher/main.go"
// Linux says: "OK, I'll tell you exactly what happens to that file"

Pros

Precise, file-level events
You know exactly what changed
Low-level control

Cons

Each watch = one file descriptor (limited resource)
Easy to hit system limits on large projects
More prone to event flooding

Example event

// Event: /home/me/fswatcher/main.go MODIFIED
// Event: /home/me/fswatcher/main.go ATTRIBUTES_CHANGED
// Event: /home/me/fswatcher/main.go CLOSE_WRITE
// Same file save = 3 events

🪟 Windows: ReadDirectoryChangesW (Async-first)

Windows philosophy: asynchronous I/O with overlapping operations.

// You say: "watch C:\project and give me async notifications"
// Windows says: "I'll buffer changes and notify you asynchronously"

Pros

Fast asynchronous I/O
Efficient buffering
Scales well

Cons

Requires careful buffer management
Can lose events if the buffer overflows
Complex synchronization needed

Example event

// Event: C:\project\main.go MODIFIED (buffered)
// Event: C:\project\test.go CREATED (buffered)
// Events may be batched by Windows

The real challenges

Challenge 1: Event Inconsistency
Same action (save a file) → different events per OS:

// macOS
Event: /project changed (directory-level)

// Linux  
Event: file.go MODIFIED
Event: file.go ATTRIB
Event: file.go CLOSE_WRITE

// Windows
Event: file.go MODIFIED (buffered)

Challenge 2: Editor Spam
Modern editors (VSCode, GoLand) don't just save once:

1. Create temp file (.file.go.tmp)
2. Write content to temp
3. Delete original
4. Rename temp to original
5. Update attributes
6. Flush buffers

That's 6+ events for ONE save operation!

Challenge 3: Bulk Operations
When you run git checkout, thousands of files change instantly:
bashgit checkout main

# 10,000 files changed
# = 10,000+ file system events in ~1 second

Your watcher must handle this flood without crashing.

A unified pipeline to solve inconsistency

In FSWatcher, I built a pipeline that normalizes all these differences:

┌─────────────┐
│ OS Events   │ (platform-specific)
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ Normalize   │ (consistent Event struct)
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ Debounce    │ (merge rapid duplicates)
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ Batch       │ (group related changes)
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ Filter      │ (regex include/exclude)
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ Clean Event │ (to consumer)
└─────────────┘

Debouncing in action

// Without debouncing:
Event: main.go changed at 10:00:00.100
Event: main.go changed at 10:00:00.150
Event: main.go changed at 10:00:00.200
Event: main.go changed at 10:00:00.250
Event: main.go changed at 10:00:00.300

// With debouncing (300ms window):
Event: main.go changed at 10:00:00.300 (final)

Batching in action

// Without batching:
10 separate event notifications

// With batching:
Batch: []Event{10 events} (one notification)

Real example

Here's a hot-reload system using FSWatcher:

go get github.com/sgtdi/fswatcher

package main

import (
    "context"
    "fmt"

    "github.com/sgtdi/fswatcher"
)

func main() {
    // Only watch .go files and ignore .go files under test dir
    fsw, _ := fswatcher.New(
        fswatcher.WithIncRegex([]string{`\.go$`}),
        fswatcher.WithExcRegex([]string{`test/.*\.go$`}),
    )

    ctx := context.Background()
    go fsw.Watch(ctx)

    fmt.Println("Starting..")
    for e := range fsw.Events() {
        fmt.Println(e.String())
        fmt.Println("Changed..")
    }
}

I also wrote a detailed article on Medium about the implementation journey and lessons learned: Read the full story

Resources

FSWatcher
Apple FSEvents Documentation
Linux inotify man page
Windows ReadDirectoryChangesW

Building a cross-platform File Watcher in Go: What I learned from scratch

Asoseil — Sun, 09 Nov 2025 11:22:16 +0000

Ever wondered how hot-reload tools actually detect when you save a file? I did too. So instead of just using an existing library, I spent weeks building one from scratch.

This is the story of FSWatcher, a cross-platform file system watcher for Go that taught me more about operating systems and concurrency than any tutorial ever could.

The problem that started everything

A while ago, I had built a simple hot-reload tool for a Go project, it worked great using fsnotify, but I had no idea what was happening under the hood. When I save a file in VSCode, how does my computer actually know that something changed?

That curiosity led me down a rabbit hole that became FSWatcher.

What makes file watching so complex?

Here's the thing: each operating system handles file monitoring completely differently.

macOS: FSEvents
On macOS, you don't watch individual files, you watch entire directory trees. Apple's FSEvents API is efficient and event-driven, but it floods you with information you don't always need.

// macOS watches directories, not files
// On file change return an event like: 
"something changed in /Users/you/project/file.txt"
// But return also events about temporary files: 
"something changed in /Users/you/project/file.txt~"
// And also many events for each action on the file, like:
 "something changed in /Users/you/project/file.txt~" CHMOD
 "something changed in /Users/you/project/file.txt~" WRITE
//and so on

Linux: inotify
Linux's inotify is more granular; you can watch specific files, but it's also more fragile. Each watch consumes a file descriptor, and on a large project, you can easily hit system limits.

// Linux is precise but limited
// Each file watch = one file descriptor
// Large projects = potential resource exhaustion due to max limits

Windows: ReadDirectoryChangesW
Windows uses asynchronous I/O with overlapping reads. It's fast, but requires careful coordination of buffers and synchronization to avoid losing events.

// Windows is async-first
// Requires buffer management and careful synchronization

The architecture challenge

The first version of FSWatcher was a mess. I had goroutines everywhere, different code paths for each OS, and events that didn't match across platforms.

The breakthrough came when I realized I needed a unified pipeline:

OS Events → Normalization → Debouncing → Batching → Clean Events

Normalization
Convert platform-specific events into a consistent format

Debouncing
When you save a file in VSCode or another editor, it might trigger 3-5 events in quick succession. Debouncing merges them into one:

// Instead of:
// Event: file.go changed
// Event: file.go changed
// Event: file.go changed

// You get a single event:
// Event: file.go changed

Batching
When there are many changes with different operations like WRITE, CREATED, CHMOD, and so on, the batch is released as a single WatchEvent.

// Instead of many individual events
// You get a single event with the multiple operations

Real problems, real solutions

None of these features was planned, they all came from actual pain points:

Problem: VSCode saves trigger 5 events per file
Solution: Debouncing with configurable cooldown

Problem: npm install creates 10,000+ events
Solution: Batching system to group related changes

Problem: I don't care about .git or node_modules changes
Solution: Regex filtering (include/exclude patterns)

Testing across platforms

After many tests, I also realized that manual testing wasn't sustainable. So i built a GitHub Actions pipeline that runs automated tests on macOS, Linux, and Windows on every commit.

yamlstrategy:
  matrix:
    os: [macos-latest, ubuntu-latest, windows-latest]

This caught race conditions and edge cases I would have never found manually or with a Docker emulation of the os

How to use FSWatcher

After all that complexity, the API is intentionally simple:

package main

import (
    "context"
    "fmt"
    "github.com/sgtdi/fswatcher"
)

func main() {
    // Create watcher for current directory
    fsw, err := fswatcher.New()
    if err != nil {
        panic(err)
    }

    // Start watching
    ctx := context.Background()
    go fsw.Watch(ctx)

    // Handle events
    for event := range fsw.Events() {
        fmt.Printf("File changed: %s\n", event.Path)
    }
}

That's it. No dependencies, no complex configuration. Just clean events. Obviously, there are a lot of additional options to personalize the workflow, but by default, it can be used with very few lines of code.

What I learned

Simplicity is hard: making something simple to use often means handling massive complexity internally

Test everything: Cross-platform code needs automated testing across all platforms

Real problems > Planned features

Every feature in FSWatcher came from actual friction. Go's concurrency model is powerful, and Goroutines made managing multiple OS backends possible

Try it yourself

FSWatcher is open source and ready to use:

go get github.com/sgtdi/fswatcher

GitHub Repository: github.com/sgtdi/fswatcher

I also wrote a deep dive article on Medium explaining the OS-level details and implementation challenges: Read the full story

What's Next?

Right now I'm actively working on:

Performance benchmarks vs other watchers
More examples and use cases
Additional filtering options

If you find it useful, star the repo! And if you find bugs or have ideas, issues and PRs are welcome.

Forem: Asoseil

From chaos to signal: Taming high-frequency OS events

Raw events vs. User intent

Event Merging and Throttling

The engine room

Using it in FSWatcher

Ignoring the noise with smart filtering

Platform-wware filtering

The fswatcher approach

Stop Hitting CTRL+C: The way to hot reload Go apps

Make the tooling invisible

Zero Config, instant feedback

Advanced workflow

Resources

Linux, macOS, and Windows broke my code, so I built a cross-platform test strategy

Cross-Platform behaviour is more different than you expect

CI setup that doesn’t hide platform behaviours

Testing strategy cross-platform

What the current tests cover effectively

Go further

When a simple order update breaks Revolut Checkout workflow

The Problem: Static state in a dynamic world

When things break

Reproduction

Root cause analysis

Workaround

What should happen

Other payment gateways

How macOS, Linux, and Windows detect file changes (and why it's hard to catch them)

The three main approaches

🍎 macOS: FSEvents (Directory-first)

🐧 Linux: inotify (File-First)

🪟 Windows: ReadDirectoryChangesW (Async-first)

The real challenges

A unified pipeline to solve inconsistency

Real example

Resources

Building a cross-platform File Watcher in Go: What I learned from scratch

The problem that started everything

What makes file watching so complex?

The architecture challenge

Real problems, real solutions

Testing across platforms

How to use FSWatcher

What I learned

Try it yourself

What's Next?

The `fswatcher` approach