Forem: Mohammad Abdolirad

Why I Built Rivaas: A Go Framework That Grows With You

Mohammad Abdolirad — Mon, 26 Jan 2026 11:51:17 +0000

I used Gin for years. Then my API grew, and things got messy.

Let me tell you why I built Rivaas. This isn't about saying other frameworks are bad. They're great. But I needed something different.

The Problem

Three years ago, I started a simple API. Just a few endpoints. I picked Gin because it was fast and popular.

The API worked well. Then the project grew.

Observability Was Bolted On

We needed to track metrics. I added Prometheus manually. Connected it to the routes. Added custom middleware.

Then we needed tracing. I added Jaeger. More middleware. More manual work.

Then we needed structured logging. Another library. More integration code.

Each piece worked. But nothing talked to each other. Logs didn't include trace IDs. Metrics didn't match route names. Every new feature meant writing more glue code.

Configuration Was Scattered

Environment variables were everywhere:

port := os.Getenv("PORT")
dbHost := os.Getenv("DB_HOST")
logLevel := os.Getenv("LOG_LEVEL")
// ... 30 more lines ...

Some config came from files. Some from env vars. Some was hardcoded. When you needed to change something, you had to search through multiple files.

No Lifecycle Management

When we shut down the server, we had to remember to:

Stop accepting new requests
Wait for current requests to finish
Close database connections
Flush metrics
Close tracing exporters

This was all manual. Miss one step and you lose data or get errors.

Validation Was Manual

Every endpoint needed validation code:

if user.Email == "" {
    return errors.New("email required")
}
if !isValidEmail(user.Email) {
    return errors.New("invalid email")
}
if user.Age < 18 {
    return errors.New("must be 18 or older")
}

Multiply this by 50 endpoints. That's a lot of boring code.

The Name: Wild Rhubarb

I needed a name for this project. I wanted something meaningful.

I thought about what I wanted the framework to be. Then I remembered ریواس (Rivās) - wild rhubarb.

This plant grows in the mountains of Iran. At 1,500 to 3,000 meters altitude. The weather is harsh. The soil is poor. Few plants can survive there.

But Rivās thrives. It has four special qualities:

1. Resilient

Rivās survives freezing winters and hot summers. It handles extreme conditions.

Your API needs to be resilient too. It should handle panics gracefully. Shut down properly. Recover from errors.

Rivaas includes panic recovery, graceful shutdown, and health checks. Your service stays up even when things go wrong.

2. Lightweight

Rivās doesn't need much. Poor soil is fine. Little water is enough.

Your framework should be the same. It shouldn't use tons of memory. It shouldn't slow down your app.

Rivaas uses 16 bytes per request. It handles 8.4 million requests per second. You don't need huge servers to run it.

3. Adaptive

Rivās grows at different altitudes. In valleys and on peaks. It adapts to its environment.

Your API runs in different places too. Your laptop. A container. A Kubernetes cluster.

Rivaas works everywhere. Same code, different environments. It detects what's available and adapts.

4. Self-Sufficient

Rivās doesn't depend on other plants. It grows on its own.

Your framework should include what you need. Not force you to find and connect dozens of libraries.

Rivaas includes metrics, tracing, logging, validation, and config management. Everything talks to each other. You don't write glue code.

These four qualities guide every decision in Rivaas.

What I Wanted

I sat down and made a list. What would my ideal framework look like?

Batteries Included, But Not Locked In

Most frameworks are either bare minimum or all-in.

Bare minimum frameworks give you routing. You add everything else yourself.

All-in frameworks give you everything. But you can't swap parts out.

I wanted both. Give me good defaults. But let me replace anything.

Rivaas works like this:

// Use the full framework
a, err := app.New(
    app.WithObservability(
        app.WithMetrics(),
        app.WithTracing(),
    ),
)

Or use just the parts you need:

// Use just the router
r := router.New()

// Add your own metrics library
// Add your own tracing
// Full control

Each package has its own go.mod. You can use one without the others.

Observability Built In, Not Added Later

Metrics, tracing, and logging should be first-class features. Not afterthoughts.

In Rivaas, observability is integrated:

Logs include trace IDs automatically
Metrics use the same service name as traces
Everything is configured in one place
It all works together

You turn it on with one option. You don't write integration code.

Production-Ready Defaults

Most frameworks give you dev-friendly defaults. Then you search for "production configuration" and copy code from Stack Overflow.

Rivaas has production-ready defaults:

Graceful shutdown with timeout
Health endpoints for Kubernetes
Panic recovery middleware
Structured JSON logging
Request timeouts

You can override anything. But the defaults work in production.

Clear Error Messages

When something goes wrong, the error should tell you exactly what happened.

Bad error: validation failed

Good error:

{
  "status": 400,
  "title": "Validation Failed",
  "detail": "The request body contains invalid data",
  "errors": [
    {
      "field": "email",
      "message": "must be a valid email address",
      "value": "not-an-email"
    },
    {
      "field": "age",
      "message": "must be at least 18",
      "value": 15
    }
  ]
}

Rivaas gives you the second type. Your frontend developers will thank you.

Design Decisions

I made some choices early on. These shaped how Rivaas works.

Modular Architecture

Each package is independent. Each has its own go.mod file.

rivaas/
├── app/          → rivaas.dev/app
├── router/       → rivaas.dev/router
├── binding/      → rivaas.dev/binding
├── validation/   → rivaas.dev/validation
├── config/       → rivaas.dev/config
├── logging/      → rivaas.dev/logging
├── metrics/      → rivaas.dev/metrics
├── tracing/      → rivaas.dev/tracing
└── ...

You install what you need:

# Full framework
go get rivaas.dev/app

# Just the router
go get rivaas.dev/router

# Just config management
go get rivaas.dev/config

Functional Options Pattern

Every package uses the same configuration pattern:

r := router.New(
    router.WithPort(8080),
    router.WithTimeout(30 * time.Second),
)

This makes the API consistent. Once you learn it in one package, you know it everywhere.

The App Package as Integration Layer

The app package doesn't have much code. It's mostly integration.

It takes all the other packages and connects them:

Sets the service name everywhere
Connects logs to traces
Sets up health checks
Manages lifecycle

You can use app for convenience. Or skip it and wire things yourself.

What Makes It Different

There are many Go frameworks. Why choose Rivaas?

Here's an honest comparison:

Feature	Rivaas	Gin	Echo	Chi
Router speed	⚡⚡⚡	⚡⚡⚡	⚡⚡⚡	⚡⚡
Built-in observability	✅	❌	❌	❌
Automatic OpenAPI	✅	❌	❌	❌
Graceful shutdown	✅	⚠️	⚠️	⚠️
Health endpoints	✅	❌	❌	❌
Modular packages	✅	❌	❌	✅
Validation strategies	3	1	1	0
Config management	✅	❌	❌	❌

(✅ = built-in, ⚠️ = basic, ❌ = not included)

Rivaas isn't always better. But it includes more out of the box.

When to Use Rivaas

Choose Rivaas if you:

Want observability without setup
Need automatic API documentation
Build cloud-native services
Want production-ready defaults
Like modular design

When Not to Use Rivaas

Don't choose Rivaas if you:

Need the absolute smallest binary
Want to control every detail
Already have a working setup with another framework
Prefer older, more stable frameworks

Be honest with yourself about your needs.

The Journey

Building Rivaas took time. Here's what I learned.

Start Small

I didn't build everything at once. I started with the router. Made it fast. Then added binding. Then validation.

Each piece got attention. Nothing was rushed.

Listen to Users

Early users had good ideas. They found bugs. They asked for features I hadn't thought about.

The OpenAPI generation came from user requests. So did the multiple validation strategies.

Make Hard Choices

I wanted to support everything. But that's impossible.

We dropped some features. We said no to some requests. This kept the codebase clean.

Every feature has a maintenance cost. We only add features that are worth it.

Document Everything

Code without docs is useless. I wrote guides for every package. Examples for every feature.

Good documentation takes longer than code. But it's worth it.

What's Next

Rivaas is ready for production. But there's more to do.

Community Growth

We need more contributors. More examples. More tutorials.

If you use Rivaas, share your experience. Write about it. Help others.

More Integrations

We want to integrate with more tools:

More database helpers
More auth strategies
More deployment examples

Performance Improvements

8.4 million requests per second is good. But we can do better.

We're always looking for optimizations. Small gains add up.

Stability and Polish

Every release makes Rivaas more stable. We fix bugs fast. We improve APIs based on feedback.

The goal is a framework you can trust in production.

How to Contribute

Want to help? Here's how:

Use Rivaas

The best way to help is to use it. Build something. Find bugs. Share feedback.

Write About It

Write a blog post. Make a video. Share on social media.

Help others discover Rivaas.

Contribute Code

Check the issues on GitHub. Look for "good first issue" tags.

Write tests. Fix bugs. Add features.

Improve Documentation

Found a confusing doc? Fix it. Missing an example? Add it.

Documentation improvements are always welcome.

Conclusion

I built Rivaas because I needed it. Maybe you need it too.

It's not perfect. No framework is. But it solves real problems.

It gives you:

Speed without complexity
Features without bloat
Flexibility without chaos
Production-ready without configuration hell

Try it in your next project. See if it fits your needs.

If it does, great. If not, that's fine too. Choose what works for you.

Get Started: go get rivaas.dev/app
Read the Docs: rivaas.dev/docs
View the Code: github.com/rivaas-dev/rivaas
Join Discussions: GitHub Discussions

Ensuring Service Availability in Modern Infrastructure with Wait4X's TCP Checker

Mohammad Abdolirad — Mon, 24 Mar 2025 16:10:13 +0000

Are you tired of race conditions in your deployment pipelines? Ever run into those pesky "connection refused" errors when your application starts before its dependencies? Today I'll introduce you to Wait4X's TCP checker - a powerful tool for ensuring your services are ready before your application tries to connect.

What is Wait4X?

Wait4X is a lightweight, zero-dependency tool designed to wait for services to be ready before continuing. It's a Swiss Army knife for service readiness checks, supporting multiple protocols and integrations including TCP, HTTP, DNS, and various databases.

The TCP Checker: Simple Yet Powerful

At its core, the TCP checker does one thing extremely well: it attempts to establish a TCP connection to a specified address and port. If the connection succeeds, the service is considered ready; if it fails, Wait4X will retry based on your configuration.

Basic Usage

The simplest way to use Wait4X's TCP checker is:

wait4x tcp localhost:3306

This command will attempt to connect to MySQL running on the default port, retrying until it succeeds or times out.

Advanced Options

Wait4X offers several options to fine-tune TCP checking behavior:

Connection timeout: Specify how long to wait for each connection attempt
```
wait4x tcp localhost:8080 --connection-timeout 5s
```
Retry interval: Control how frequently to retry
```
wait4x tcp localhost:8080 --interval 2s
```

Exponential backoff: Use smarter retry strategies

wait4x tcp localhost:8080 --backoff-policy exponential --backoff-exponential-coefficient 2.0

Multiple endpoints: Check multiple services in parallel

wait4x tcp localhost:3306 localhost:6379 localhost:27017

Reverse checking: Wait for a port to become free
```
wait4x tcp localhost:8080 --invert-check
```

Real-world Use Cases

Docker Compose Orchestration

When working with Docker Compose, you often have dependencies between services. Using Wait4X, you can ensure services start in the right order:

services:
  db:
    image: postgres:13
    ports:
      - "5432:5432"
    # ...

  api:
    build: ./api
    # ...
    depends_on:
      - db
    command: sh -c "wait4x tcp db:5432 && npm start"

CI/CD Pipelines

In CI/CD pipelines, Wait4X ensures tests don't run until services are ready:

# Start services
docker-compose up -d

# Wait for services to be ready
wait4x tcp localhost:3306 localhost:6379

# Run tests
npm test

Kubernetes Init Containers

Wait4X is perfect for Kubernetes init containers:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  # ...
  template:
    spec:
      initContainers:
        - name: wait-for-db
          image: wait4x/wait4x:latest
          command: [ "wait4x", "tcp", "postgres-service:5432", "--timeout", "60s" ]
      containers:
        - name: app
          image: my-app:latest
          # ...

Using Wait4X as a Go Package

For Go developers, Wait4X provides a clean API:

// Create a context with timeout
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

// Create a TCP checker
tcpChecker := tcp.New("localhost:6379", tcp.WithTimeout(5*time.Second))

// Wait for the TCP port to be available
err := waiter.WaitContext(
    ctx,
    tcpChecker,
    waiter.WithTimeout(time.Minute),
    waiter.WithInterval(2*time.Second),
    waiter.WithBackoffPolicy("exponential"),
)
if err != nil {
    log.Fatalf("Failed to connect: %v", err)
}

fmt.Println("Service is ready!")

How it Works Under the Hood

Wait4X's TCP checker uses Go's net.Dialer.DialContext to attempt TCP connections with configurable timeouts. It handles various error cases intelligently, distinguishing between connection refusals, timeouts, and other network issues.

The exponential backoff strategy progressively increases the interval between retries, reducing unnecessary connection attempts while still responding quickly when services become available.

Conclusion

Wait4X's TCP checker solves a common but critical challenge in modern infrastructure: ensuring services are actually ready before dependent applications attempt to connect. By providing a simple, reliable way to check TCP connectivity, Wait4X helps eliminate race conditions, reduce errors, and make your deployments more robust.

Give Wait4X a try in your next project - your deployment pipelines will thank you!

What service readiness problems have you encountered in your infrastructure? Share your experiences in the comments!