humanirvana

package module

v0.1.0 Latest Latest Go to latest Published: Oct 22, 2026 License: MIT Imports: 15 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/alswl/humanirvana

Links

Open Source Insights

README ¶

Humanirvana

A thin Huma adapter for the existing Nirvana router. New Huma operations and legacy Nirvana descriptors share one routing tree, so you can migrate one operation at a time.

Status: experimental. Full Huma support and real-application migration are not established. CBOR and media unknown to Nirvana return 415. See the compatibility reference before you use it.

Install

Requires Go 1.23 or later.

go get github.com/alswl/humanirvana

Dependencies: Huma v2.35.0 and Nirvana v0.3.1, unmodified.

Usage

builder := rest.NewBuilder()
adapter := humanirvana.NewAdapter(builder)
api := huma.NewAPI(huma.DefaultConfig("My API", "1.0.0"), adapter)

// New operations: huma.Register(api, ...)
// Existing descriptors: humanirvana.RegisterLegacy(builder, descriptors)

handler, err := builder.Build()
if err != nil {
	return err
}
if err := adapter.Bind(handler); err != nil {
	return err
}
// Serve adapter with your HTTP server.

Register everything before Build, then Bind once. Legacy routes keep Nirvana's execution chain and do not appear in Huma's OpenAPI. Your application owns startup, configuration, dependencies and shutdown.

Documentation

License

Apache License 2.0. See LICENSE.

Documentation ¶

Overview ¶

Package humanirvana connects a standard Huma API to an existing Nirvana builder.

Index ¶

func RegisterLegacy(builder service.Builder, descriptors []definition.Descriptor) error
type Adapter
- func NewAdapter(builder service.Builder) *Adapter

Constants ¶

This section is empty.

Variables ¶

This section is empty.

Functions ¶

func RegisterLegacy ¶

func RegisterLegacy(builder service.Builder, descriptors []definition.Descriptor) error

RegisterLegacy adds existing descriptors directly to the application's Nirvana builder. Their handler, middleware, binding, and response behavior remain on Nirvana's original execution path.

Types ¶

type Adapter ¶

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

Adapter registers Huma operations on an application-owned Nirvana builder. Build the builder after all Huma registrations, then Bind its service before serving requests through the API's Adapter.

func NewAdapter ¶

func NewAdapter(builder service.Builder) *Adapter

NewAdapter attaches Huma registrations to the existing Nirvana builder.

func (*Adapter) Bind ¶

func (a *Adapter) Bind(handler http.Handler) error

Bind makes the application-built Nirvana service handle Huma Adapter requests. It must be called once, after builder.Build succeeds and before serving.

func (*Adapter) Handle ¶

func (a *Adapter) Handle(op *huma.Operation, handler func(huma.Context))

Handle registers a Huma callback as a context-aware Nirvana definition. Nirvana owns route matching, media admission, filters and node middleware. Huma owns the callback's binding, validation and response serialization.

func (*Adapter) ServeHTTP ¶

func (a *Adapter) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP delegates to the service built by the application. It never builds the router implicitly.

Source Files ¶

View all Source files

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
examples
basic Package reviewcombination exposes one deterministic native Huma operation with an optional, independent Nirvana legacy route for human inspection.	Package reviewcombination exposes one deterministic native Huma operation with an optional, independent Nirvana legacy route for human inspection.
basic/cmd command
coexist Package showcase is a synthetic service used to compare the original Nirvana runtime with direct Huma registration plus the legacy adapter entry.	Package showcase is a synthetic service used to compare the original Nirvana runtime with direct Huma registration plus the legacy adapter entry.
coexist/cmd command
middleware command Command middleware shows authentication, request-ID logging and an application-owned dependency shared by a legacy Nirvana descriptor and a Huma operation on one Nirvana router.	Command middleware shows authentication, request-ID logging and an application-owned dependency shared by a legacy Nirvana descriptor and a Huma operation on one Nirvana router.
internal
middleware Package middleware provides middleware bridging from Nirvana to Huma.	Package middleware provides middleware bridging from Nirvana to Huma.
pilot Package pilot provides a constrained legacy-handler migration demo.	Package pilot provides a constrained legacy-handler migration demo.
router Package router provides route conversion from Nirvana Definition to Huma Operation.	Package router provides route conversion from Nirvana Definition to Huma Operation.
tests
compatibility Package demo is a test-first migration application using shared Nirvana handlers.	Package demo is a test-first migration application using shared Nirvana handlers.
compatibility/cmd command
compatibility/internal/testkit Package testkit builds native Huma fixtures on the application's Nirvana router.	Package testkit builds native Huma fixtures on the application's Nirvana router.
integration/huma Package huma is a demo Huma migrated project for migration testing.	Package huma is a demo Huma migrated project for migration testing.
integration/huma/cmd command
integration/nirvana Package nirvana is a demo Nirvana project for migration testing.	Package nirvana is a demo Nirvana project for migration testing.
integration/nirvana/cmd command
performance/fixture Package fixture defines the PERF-01 technical fixture: the same five Huma operations served by a standard Huma arm (humago on net/http) and by the adapter arm (humanirvana on a Nirvana router).	Package fixture defines the PERF-01 technical fixture: the same five Huma operations served by a standard Huma arm (humago on net/http) and by the adapter arm (humanirvana on a Nirvana router).
performance/loadgen command Command loadgen runs one closed-loop PERF-01 measurement against a running arm: warm up, then sample until both the minimum duration and minimum request count are reached (bounded by a maximum duration).	Command loadgen runs one closed-loop PERF-01 measurement against a running arm: warm up, then sample until both the minimum duration and minimum request count are reached (bounded by a maximum duration).
performance/perf01 command Command perf01 runs the full PERF-01 protocol: for every request set P01–P05 and concurrency 1/8/32 it collects 5 valid native/adapter pairs (at most 2 extra attempts), each arm on a fresh server process, and judges every pair by P95(adapter) − P95(native) < 1000µs.	Command perf01 runs the full PERF-01 protocol: for every request set P01–P05 and concurrency 1/8/32 it collects 5 valid native/adapter pairs (at most 2 extra attempts), each arm on a fresh server process, and judges every pair by P95(adapter) − P95(native) < 1000µs.
performance/server command Command server serves one PERF-01 arm on loopback until SIGTERM.	Command server serves one PERF-01 arm on loopback until SIGTERM.
unit/cover01 Package cover01 implements the COVER-01 gate: statement-weighted coverage of the adapter library packages must satisfy 100covered >= 80total, computed from one atomic profile with raw integer counts.	Package cover01 implements the COVER-01 gate: statement-weighted coverage of the adapter library packages must satisfy 100covered >= 80total, computed from one atomic profile with raw integer counts.
unit/cover01/cmd command Command cover01 checks a coverage profile against the COVER-01 gate and writes a JSON summary.	Command cover01 checks a coverage profile against the COVER-01 gate and writes a JSON summary.