App

Overview

The App package provides a high-level, opinionated framework built on top of the Rivaas router. It includes:

• Integrated observability (metrics, tracing, logging)
• Lifecycle management with hooks
• Graceful shutdown handling
• Health and debug endpoints
• OpenAPI spec generation
• Request binding and validation

Package Information

• Import Path: rivaas.dev/app
• Go Version: 1.25+
• License: Apache 2.0

Architecture

┌─────────────────────────────────────────┐
│           Application Layer             │
│  (app package)                          │
│                                         │
│  • Configuration Management             │
│  • Lifecycle Hooks                      │
│  • Observability Integration            │
│  • Server Management                    │
│  • Request Binding/Validation           │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│           Router Layer                  │
│  (router package)                       │
│                                         │
│  • HTTP Routing                         │
│  • Middleware Chain                     │
│  • Request Context                      │
│  • Path Parameters                      │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│        Standard Library                 │
│  (net/http)                             │
└─────────────────────────────────────────┘

Quick Reference

Core Types

• App - Main application type
• Context - Request context with app-level features
• HandlerFunc - Handler function type

Key Functions

• New() - Create a new app (returns error)
• MustNew() - Create a new app (panics on error)

Configuration

• Options - App-level configuration options
• Server Options - Server configuration
• Observability Options - Metrics, tracing, logging
• Health Options - Health endpoint configuration
• Debug Options - Debug endpoint configuration
• MCP Debug Options - MCP debug server configuration
• MCP Options - Business MCP server configuration

API Reference

• API Reference - Core types and methods
• Context API - Context methods for request handling
• Lifecycle Hooks - Hook APIs and execution order

Resources

• Troubleshooting - Common issues and solutions
• pkg.go.dev - Full API documentation

App Type

The main application type that wraps the router with app-level features.

type App struct {
    // contains filtered or unexported fields
}

Creating Apps

// Returns (*App, error) for error handling
a, err := app.New(
    app.WithServiceName("my-api"),
    app.WithServiceVersion("v1.0.0"),
)
if err != nil {
    log.Fatal(err)
}

// Panics on error (like regexp.MustCompile)
a := app.MustNew(
    app.WithServiceName("my-api"),
)

Options must not be nil; passing a nil option results in an error (or panic with MustNew).

HTTP Methods

Register routes for HTTP methods:

a.GET(path string, handler HandlerFunc, opts ...RouteOption) *route.Route
a.POST(path string, handler HandlerFunc, opts ...RouteOption) *route.Route
a.PUT(path string, handler HandlerFunc, opts ...RouteOption) *route.Route
a.DELETE(path string, handler HandlerFunc, opts ...RouteOption) *route.Route
a.PATCH(path string, handler HandlerFunc, opts ...RouteOption) *route.Route
a.HEAD(path string, handler HandlerFunc, opts ...RouteOption) *route.Route
a.OPTIONS(path string, handler HandlerFunc, opts ...RouteOption) *route.Route
a.Any(path string, handler HandlerFunc, opts ...RouteOption) *route.Route

Only the listed methods are supported; unsupported method causes a panic. See API Reference for details.

Server Management

a.Start(ctx context.Context) error

Configure HTTP, HTTPS, or mTLS at construction with WithTLS or WithMTLS.

Lifecycle Hooks

a.OnStart(fn func(context.Context) error) error
a.OnReady(fn func()) error
a.OnShutdown(fn func(context.Context)) error
a.OnStop(fn func()) error
a.OnRoute(fn func(*route.Route)) error
a.OnReload(fn func(context.Context) error) error

See Lifecycle Hooks for details.

Context Type

Request context that extends router.Context with app-level features.

type Context struct {
    *router.Context
    // contains filtered or unexported fields
}

Request Binding

c.Bind(out any, opts ...BindOption) error
c.MustBind(out any, opts ...BindOption) bool
c.BindOnly(out any, opts ...BindOption) error
c.Validate(v any, opts ...ValidateOption) error

Error Handling

c.Fail(err error)
c.FailStatus(status int, err error)
c.NotFound(err error)
c.BadRequest(err error)
c.Unauthorized(err error)
c.Forbidden(err error)
c.Conflict(err error)
c.Gone(err error)
c.UnprocessableEntity(err error)
c.TooManyRequests(err error)
c.InternalError(err error)
c.ServiceUnavailable(err error)

Logging

There is no Context.Logger() method. When the app enables observability logging, it sets the slog default logger at startup. From handlers, use slog.InfoContext(c.RequestContext(), ...) (or ErrorContext, etc.) for trace correlation; outside handlers use app.BaseLogger() or the default logger. See Context API for details.

HandlerFunc

Handler function type that receives an app Context.

type HandlerFunc func(*Context)

Example:

func handler(c *app.Context) {
    c.JSON(http.StatusOK, data)
}

a.GET("/", handler)

Next Steps

• API Reference - Complete API documentation
• Options - Configuration options reference
• Troubleshooting - Common issues and solutions
• User Guide - Learn how to use the app package