chi

README

vormia-go-driver-chi

Chi router adapter for the Vormia Go framework. Thin wrapper around go-chi/chi that exposes an idiomatic HTTP routing API with middleware support — without leaking the underlying Chi types to your app.

Version: v1.1.0 — includes Routes() for vormia-go v1.2.0+ contract.Router.

Install

go get github.com/vormialabs/vormia-go-driver-chi@v1.1.0

Quick start

package main

import (
	"net/http"

	chi "github.com/vormialabs/vormia-go-driver-chi"
)

func main() {
	r := chi.New()
	r.Use(chi.CORS())

	r.Get("/health", func(w http.ResponseWriter, _ *http.Request) {
		_ = chi.JSON(w, http.StatusOK, map[string]string{"status": "ok"})
	})

	// Route mounts a sub-router under a path prefix.
	r.Route("/api", func(api *chi.Router) {
		api.Get("/users/{id}", func(w http.ResponseWriter, req *http.Request) {
			_ = chi.Success(w, http.StatusOK, map[string]string{
				"id": chi.URLParam(req, "id"),
			})
		})
	})

	_ = r.Serve(":8080")
}

API overview

Router

Method	Purpose
New()	Create a router (no args)
Get / Post / Put / Patch / Delete / Head / Options	Register routes
Use(mw ...Middleware)	Global middleware — call before routes
Group(fn)	Inline sub-router, inherits middleware, no path prefix
Route(prefix, fn)	Sub-router mounted under a path prefix (e.g. "/api")
Serve(addr)	Start blocking http.Server
Shutdown(ctx)	Graceful shutdown
ServeHTTP / Handler()	Use as a plain http.Handler
Routes()	List registered method+pattern pairs (chi.Walk)

Helpers

• JSON(w, status, data) — raw JSON body
• Success(w, status, data) — {"data": ...}
• Error(w, status, message) — {"error": "..."}
• URLParam(r, key) — read {id}-style path params (re-exported so you never import go-chi)
• CORS(origins...) — permissive CORS middleware (default origin *)

Path params

Chi uses {id} syntax, not :id:

r.Get("/users/{id}", func(w http.ResponseWriter, req *http.Request) {
	id := chi.URLParam(req, "id")
	_ = chi.JSON(w, http.StatusOK, map[string]string{"id": id})
})

Group vs Route

// Group: same path space, shared middleware only
r.Group(func(sub *chi.Router) {
	sub.Use(authMiddleware)
	sub.Get("/profile", profileHandler)
})

// Route: mounted under a prefix
r.Route("/api", func(api *chi.Router) {
	api.Get("/ping", pingHandler) // → GET /api/ping
})

Example

See examples/basic for a runnable smoke-test server:

go run ./examples/basic
curl -i localhost:8080/health
curl -i localhost:8080/api/users/42

Docs worth knowing

• go-chi/chi — routing, middleware order, {param} patterns
• net/http — Handler, HandlerFunc, Server, graceful Shutdown
• httptest — in-memory request testing

License

MIT

Documentation

Index

• func Error(w http.ResponseWriter, status int, message string) error
• func JSON(w http.ResponseWriter, status int, data any) error
• func Success(w http.ResponseWriter, status int, data any) error
• func URLParam(r *http.Request, key string) string
• type Middleware
  • func CORS(origins ...string) Middleware
• type Router
  • func New() *Router
  • func (r *Router) Delete(pattern string, h http.HandlerFunc)
  • func (r *Router) Get(pattern string, h http.HandlerFunc)
  • func (r *Router) Group(fn func(sub *Router))
  • func (r *Router) Handler() http.Handler
  • func (r *Router) Head(pattern string, h http.HandlerFunc)
  • func (r *Router) Options(pattern string, h http.HandlerFunc)
  • func (r *Router) Patch(pattern string, h http.HandlerFunc)
  • func (r *Router) Post(pattern string, h http.HandlerFunc)
  • func (r *Router) Put(pattern string, h http.HandlerFunc)
  • func (r *Router) Route(prefix string, fn func(sub *Router))
  • func (r *Router) Routes() []struct{ ... }
  • func (r *Router) Serve(addr string) error
  • func (r *Router) ServeHTTP(w http.ResponseWriter, req *http.Request)
  • func (r *Router) Shutdown(ctx context.Context) error
  • func (r *Router) Use(mw ...Middleware)

Functions

func Error

func Error(w http.ResponseWriter, status int, message string) error

Error writes a JSON error envelope: {"error": "..."}.

func JSON

func JSON(w http.ResponseWriter, status int, data any) error

JSON writes a JSON body with the given status code. Note: WriteHeader is called before Encode, so once JSON starts writing you can no longer change the status. Validate/marshal-check earlier if that matters for a given handler.

func Success

func Success(w http.ResponseWriter, status int, data any) error

Success writes a JSON data envelope: {"data": ...}.

func URLParam

func URLParam(r *http.Request, key string) string

URLParam extracts a path parameter (e.g. {id}) from the request. Re-exported so applications never import go-chi directly.

Types

type Middleware

type Middleware = func(http.Handler) http.Handler

Middleware is the standard net/http middleware signature. It's an alias (not a new type) so it's interchangeable with plain func(http.Handler) http.Handler everywhere.

func CORS

func CORS(origins ...string) Middleware

CORS returns a permissive CORS middleware. Pass a single origin to restrict it; default is "*".

type Router

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

Router wraps a go-chi mux and exposes a Vormia-friendly API. The concrete *Router will structurally satisfy the Router interface that vormia-go defines later — no framework import required.

func New

func New() *Router

New creates a Router backed by go-chi.

func (*Router) Delete

func (r *Router) Delete(pattern string, h http.HandlerFunc)

func (*Router) Get

func (r *Router) Get(pattern string, h http.HandlerFunc)

func (*Router) Group

func (r *Router) Group(fn func(sub *Router))

Group runs fn on an inline sub-router that inherits middleware. No path prefix — use this to apply middleware to a set of routes.

func (*Router) Handler

func (r *Router) Handler() http.Handler

Handler returns the underlying handler.

func (*Router) Head

func (r *Router) Head(pattern string, h http.HandlerFunc)

func (*Router) Options

func (r *Router) Options(pattern string, h http.HandlerFunc)

func (*Router) Patch

func (r *Router) Patch(pattern string, h http.HandlerFunc)

func (*Router) Post

func (r *Router) Post(pattern string, h http.HandlerFunc)

func (*Router) Put

func (r *Router) Put(pattern string, h http.HandlerFunc)

func (*Router) Route

func (r *Router) Route(prefix string, fn func(sub *Router))

Route mounts a sub-router under a path prefix (e.g. "/api").

func (*Router) Routes

func (r *Router) Routes() []struct {
	Method  string
	Pattern string
}

Routes returns every registered method+pattern pair, via chi.Walk. The return type matches vormia-go's contract.RouteInfo alias (anonymous struct) without importing the framework.

func (*Router) Serve

func (r *Router) Serve(addr string) error

Serve builds an *http.Server and blocks serving requests.

func (*Router) ServeHTTP

func (r *Router) ServeHTTP(w http.ResponseWriter, req *http.Request)

ServeHTTP makes *Router itself an http.Handler (handy for tests and for embedding behind other handlers).

func (*Router) Shutdown

func (r *Router) Shutdown(ctx context.Context) error

Shutdown gracefully stops the server started by Serve.

func (*Router) Use

func (r *Router) Use(mw ...Middleware)

Use registers global middleware. Must be called BEFORE routes are added.