NERVA

BUILD. SECURE. CONNECT.

A lightweight Go framework for building secure, real-time, and network-native applications.

Project status: Pre-1.0. NERVA is currently developing its v0.1 HTTP core. APIs may change, and no pre-1.0 snapshot should be treated as production-ready. A roadmap item is not an implemented feature.

Why NERVA

NERVA is intended for APIs, backend services, and operational control planes that need an idiomatic HTTP foundation today and well-defined security, realtime, and network-oriented modules over time. Its design favors the Go standard library, explicit composition, predictable lifecycle behavior, and evidence-led optimization.

NERVA owns its public API, routing, context, middleware, error handling, and lifecycle. It does not use Gin, Fiber, Echo, Chi, or another full framework as its runtime.

Quick Start

The v0.1 API is being shaped around this minimal application:

package main

import (
    "net/http"

    "github.com/nerva-framework/nerva"
)

func main() {
    app := nerva.New()

    app.Get("/", func(c *nerva.Context) error {
        return c.JSON(http.StatusOK, nerva.Map{
            "name":    "NERVA",
            "message": "BUILD. SECURE. CONNECT.",
        })
    })

    if err := app.Run(":8080"); err != nil {
        panic(err)
    }
}

Until a v0.1 release is tagged, use the repository source directly and expect API evolution.

Features

The v0.1 engineering scope is deliberately narrow:

• a net/http foundation and NERVA-owned router;
• the Handler func(*Context) error contract and centralized HTTP errors;
• static and parameterized routes with HTTP method dispatch;
• request context helpers and JSON/text responses;
• composable global, group, and route middleware;
• Recovery, RequestID, and SecurityHeaders enabled by default, with Logger opt-in;
• a built-in GET /health endpoint and graceful server shutdown;
• unit, race, vet, security, and benchmark-smoke checks; and
• microbenchmark and comparison-harness foundations.

This list defines the v0.1 target. See the changelog and tests for the exact state of a particular commit.

Architecture

NERVA builds on net/http while keeping framework concepts small and explicit. Routes are registered into a simple static index and route table; complexity such as a radix tree is deferred until measurements justify it. The context wraps request-scoped behavior, handlers return errors to one central policy, and middleware composes handlers without hidden dependency injection.

See Architecture and the architecture decision records.

Routing

The v0.1 route model covers static paths such as /health, parameterized paths such as /devices/:id, nested parameters, method dispatch, 404/405 behavior, groups, and deterministic middleware composition. Wildcard routes and more complex indexes are future work unless benchmark evidence establishes a need.

Security

Secure-by-default is a design constraint, not a claim that the framework makes an application secure by itself. The v0.1 core focuses on safe server timeouts, bounded configuration, generic production errors, panic recovery, request-ID validation, security headers, and avoiding secret logging. Authentication, authorization, rate limiting, body limits, audit logging, and CORS are planned for v0.2 and are not part of the v0.1 core.

See Security design and the security policy.

Realtime

Realtime features are not part of v0.1. A bounded event bus and Server-Sent Events are planned for v0.3; WebSocket support may follow after the core and lifecycle model are stable.

Network Native

Network-oriented modules are intentionally separate from the HTTP core. Vendor-neutral devices, credential providers, TCP checks, and network events are planned for v0.4. SSH, SNMP, adapters, and monitoring are planned for v0.5. These packages must not burden applications that only import the core.

Performance

Performance is measured, not advertised. NERVA currently makes no comparative HTTP throughput, socket-latency, or production performance claim. The current benchmark report is explicitly a noncanonical, in-process development diagnostic. Engineering goals include remaining reasonably close to raw net/http, limiting hot-path allocations, and keeping latency predictable under concurrency without weakening correctness or security.

See Performance.

Benchmarks

The repository establishes benchmark methodology alongside the v0.1 core. Results are valid only when accompanied by environment metadata, equivalent workloads, warm-up, repeated runs, raw data, and limitations. Missing or failed runs are reported as such; they are never replaced with zeroes. BENCHMARKS.md, when present, is a generated report rather than a marketing document.

See Benchmark methodology.

CLI

v0.1 includes an experimental, offline project creator. From a source checkout:

go run ./cmd/nerva new first-project

After the repository has a public release tag, the native installation flow will be:

go install github.com/nerva-framework/nerva/cmd/nerva@latest
nerva new first-project

The equivalent npm launcher will be available after create-nerva-app is published:

npx create-nerva-app first-project

Developers who prefer an installed npm command can use npm install --global create-nerva-app once and then run create-nerva-app first-project.

Use --module example.com/you/first-project when the Go module path should differ from the destination directory. The creator writes a minimal Go application without running go get, go mod tidy, or another networked command, and it refuses to overwrite an existing destination.

These public @latest commands require the corresponding GitHub release and npm publication. The source-checkout command exercises the generator before release; compiling that generated project also requires the temporary local replace documented in the CLI guide. A mature CLI with run, routes, doctor, and benchmark tooling remains planned for v0.6.

Roadmap

The project advances in measured stages: HTTP core, security, realtime, network core, network automation, CLI, observability, performance hardening, release candidate, then v1.0. See the roadmap.

Documentation

• Architecture
• Security design
• Performance policy
• Benchmark methodology
• CLI and project creator
• Roadmap
• Architecture decisions

Contributing

Contributions are welcome while the project is pre-1.0. Please read CONTRIBUTING.md and the Code of Conduct. Changes to a public API, hot path, security default, or benchmark method need rationale and focused tests.

Security Policy

Do not report suspected vulnerabilities in a public issue. Follow SECURITY.md for private reporting guidance.

License

NERVA is licensed under the Apache License 2.0.