Rivaas

A batteries-included, cloud-native web framework for Go featuring high-performance routing (8.4M+ req/sec), comprehensive request binding & validation, automatic OpenAPI generation, and OpenTelemetry-native observability.

Metric	Value
Throughput	8.4M+ req/sec
Latency	119ns average
Memory	16 bytes/request

^{Benchmarked on Intel i7-1265U. See benchmarks for methodology and comparisons.}

Quick Start

package main

import (
    "context"
    "log"
    "net/http"
    "os"
    "os/signal"
    "syscall"

    "rivaas.dev/app"
)

func main() {
    a, err := app.New()
    if err != nil {
        log.Fatal(err)
    }

    a.GET("/", func(c *app.Context) {
        c.JSON(http.StatusOK, map[string]string{"message": "Hello from Rivaas!"})
    })

    ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
    defer cancel()

    if err := a.Start(ctx, ":8080"); err != nil {
        log.Fatal(err)
    }
}

With observability:

a, err := app.New(
    app.WithServiceName("my-api"),
    app.WithObservability(
        app.WithLogging(logging.WithConsoleHandler()),
        app.WithMetrics(), // Prometheus on :9090/metrics
        app.WithTracing(tracing.WithStdout()),
    ),
)

See full-featured example for a complete production setup.

Installation

go get rivaas.dev/app

Requires Go 1.25+

Philosophy

The name Rivaas comes from ریواس (Rivās) — a wild rhubarb plant native to the mountains of Iran.

This plant grows at high altitudes (1,500–3,000 meters) in harsh, rocky terrain where few other plants survive. It withstands extreme temperature swings, poor soil, and unpredictable weather — yet it thrives, providing food and medicine to mountain communities for centuries.

That's the philosophy behind Rivaas:

Principle	Description
🛡️ Resilient	Built for production with graceful shutdown, health checks, and panic recovery
⚡ Lightweight	Minimal overhead (119ns latency, 16 bytes/request) without sacrificing features
🔧 Adaptive	Works locally, in containers, or across distributed systems with the same code
📦 Self-sufficient	Integrated observability (metrics, tracing, logging) instead of bolted-on dependencies

Like its namesake growing in the mountains, Rivaas is designed to thrive in dynamic, cloud-native environments — lightweight yet powerful, modular yet simple.

Why Rivaas?

• Production-Ready — Graceful shutdown, health endpoints, panic recovery, mTLS
• High Performance — Radix tree router with Bloom filter optimization
• Flexible — Use app for batteries-included or router for full control
• Cloud-Native — OpenTelemetry-native with Prometheus, OTLP, Jaeger support
• Modular — Each package works standalone without the full framework

Packages

Core

Package	Description	Docs
app	Batteries-included web framework
router	High-performance HTTP router

Configuration

Package	Description	Docs
config	Configuration management (files, env vars, Consul, validation)

Data Handling

Package	Description	Docs
binding	Request binding (query, form, JSON, headers, XML, YAML, MsgPack, Proto)
validation	Struct validation with tags and JSON Schema

Observability

Package	Description	Docs
logging	Structured logging with slog
metrics	OpenTelemetry metrics (Prometheus, OTLP)
tracing	Distributed tracing (OTLP, Jaeger, stdout)

API & Errors

Package	Description	Docs
openapi	Automatic OpenAPI 3.0/3.1 generation with Swagger UI
errors	Error formatting (RFC 9457, JSON:API)

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     rivaas.dev/app                          │
│              Batteries-included framework                   │
├─────────────────────────────────────────────────────────────┤
│                    rivaas.dev/router                        │
│              High-performance HTTP router                   │
├───────────────┬───────────────┬─────────────────────────────┤
│   logging     │    metrics    │          tracing            │
│   binding     │   validation  │          openapi            │
│   errors      │    config     │                             │
└───────────────┴───────────────┴─────────────────────────────┘

Each package is independently usable with its own go.mod. The app package integrates them with automatic service metadata propagation and lifecycle management.

Configuration

a, err := app.New(
    app.WithServiceName("my-api"),
    app.WithServiceVersion("v1.0.0"),
    app.WithObservability(
        app.WithLogging(logging.WithJSONHandler()),
        app.WithMetrics(),
        app.WithTracing(tracing.WithOTLP("localhost:4317")),
    ),
    app.WithHealthEndpoints(
        app.WithReadinessCheck("database", dbPingCheck),
    ),
)

See App Documentation for complete configuration options.

Middleware

12 production-ready middleware included: accesslog, recovery, cors, requestid, timeout, ratelimit, basicauth, bodylimit, compression, security, methodoverride, trailingslash.

→ Middleware Documentation

Examples

Directory	Description
App Examples	Quick start and full-featured apps
Router Examples	Routing, middleware, versioning, static files
Middleware Examples	All middleware usage with curl commands

Performance

Metric	Value
Throughput	8.4M+ req/sec
Latency	119ns average
Memory	16 bytes/request
Allocations	1 per request

→ Benchmarks — detailed comparisons with Gin, Echo, Chi, Fiber

Repository Structure

Multi-module repository — each package has its own go.mod and can be versioned independently.

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
├── openapi/      → rivaas.dev/openapi
├── errors/       → rivaas.dev/errors
└── go.work       → workspace configuration

Documentation

Resource	Description
App Guide	Complete framework documentation
Router Guide	HTTP routing and request handling
Config Guide	Configuration management
Middleware Catalog	All 12 middleware with examples
Design Principles	Architecture and design decisions
Testing Standards	Testing guidelines and patterns

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Write tests for your changes
4. Ensure all tests pass (go test ./...)
5. Open a Pull Request

License

Apache License 2.0 - see LICENSE for details.

---

Made with ❤️ for the Go community