minato

README

Minato

Minato is an opinionated, fast, and feature-rich HTTP server framework for Go, designed for building production-ready microservices with minimal boilerplate.

Features

• Graceful Shutdown: Built-in signal handling and dependency teardown.
• Observability: Structured logging (log/slog), Request ID generation, and automatic Prometheus metrics.
• Resilience: Panic recovery middleware to keep your server alive.
• Health Checks: Automatic /healthz (liveness) and /readyz (readiness) endpoints with concurrent dependency checking.
• Security: Highly configurable CORS middleware.
• Routing: Clean, chi-backed routing with sub-router groups.

Installation

go get github.com/dwikynator/minato

Quick Start

Here is a minimal example of a Minato server with all the bells and whistles:

package main

import (
	"context"
	"encoding/json"
	"fmt"
	"net/http"
	"time"

	"github.com/dwikynator/minato"
	"github.com/dwikynator/minato/middleware"
)

func main() {
	// 1. Configure the server
	server := minato.New(
		minato.WithAddr(":8080"),
		minato.WithHealthCheck(),
		minato.WithMetrics(),
		minato.WithReadinessCheck("database", checkDatabase),
		minato.WithCloser("database", func() error {
			fmt.Println("Closing database connection...")
			return nil
		}),
	)

	// 2. Register Global Middleware
	server.Use(middleware.RequestID())
	server.Use(middleware.Recovery())
	server.Use(middleware.Logger(
		middleware.WithBodyLogging(true),
	))
	server.Use(middleware.CORS(
		middleware.WithAllowedOrigins("*"),
	))

	// 3. Register Routes
	server.Router().Get("/ping", func(w http.ResponseWriter, r *http.Request) {
		w.Header().Set("Content-Type", "application/json")
		w.WriteHeader(http.StatusOK)
		json.NewEncoder(w).Encode(map[string]string{"status": "ok"})
	})

	// 4. Start the server (blocks until SIGINT/SIGTERM)
	if err := server.Run(); err != nil {
		panic(err)
	}
}

func checkDatabase(ctx context.Context) error {
	// Check connection here
	return nil
}

License

MIT License

Documentation

Overview

Package minato provides an opinionated, fast, and feature-rich HTTP server framework built on top of standard library net/http and chi.

Index

• type Option
  • func WithAddr(addr string) Option
  • func WithCloser(name string, fn func() error) Option
  • func WithHealthCheck() Option
  • func WithIdleTimeout(d time.Duration) Option
  • func WithMetrics() Option
  • func WithReadHeaderTimeout(d time.Duration) Option
  • func WithReadinessCheck(name string, fn func(ctx context.Context) error) Option
  • func WithShutdownTimeout(d time.Duration) Option
• type Router
  • func (r *Router) Delete(pattern string, h http.HandlerFunc)
  • func (r *Router) Get(pattern string, h http.HandlerFunc)
  • func (r *Router) Group(pattern string, fn func(r *Router))
  • 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) ServeHTTP(w http.ResponseWriter, req *http.Request)
  • func (r *Router) Use(middlewares ...func(http.Handler) http.Handler)
• type Server
  • func New(opts ...Option) *Server
  • func (s *Server) Router() *Router
  • func (s *Server) Run() error
  • func (s *Server) Use(middlewares ...func(http.Handler) http.Handler)

Types

type Option

type Option func(*config)

Option defines a functional configuration option for the Minato Server.

func WithAddr

func WithAddr(addr string) Option

WithAddr sets the TCP address for the server to listen on. Defaults to ":8080"

func WithCloser

func WithCloser(name string, fn func() error) Option

WithCloser registers a teardown function that will be called during graceful shutdown.

func WithHealthCheck

func WithHealthCheck() Option

WithHealthCheck enables automatic registration of /healthz and /readyz endpoints.

func WithIdleTimeout

func WithIdleTimeout(d time.Duration) Option

WithIdleTimeout sets the maximum amount of time to wait for the next request when keep-alives are enabled. Defaults to 60 seconds.

func WithMetrics

func WithMetrics() Option

WithMetrics enables automatic registration of the Prometheus /metrics endpoint.

func WithReadHeaderTimeout

func WithReadHeaderTimeout(d time.Duration) Option

WithReadHeaderTimeout sets the amount of time allowed to read request headers. Defaults to 5 seconds.

func WithReadinessCheck

func WithReadinessCheck(name string, fn func(ctx context.Context) error) Option

WithReadinessCheck registers a named dependency check for the /readyz endpoint.

func WithShutdownTimeout

func WithShutdownTimeout(d time.Duration) Option

WithShutdownTimeout sets the deadline for graceful shutdown. Defaults to 30 seconds.

type Router

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

Router is a wrapper around chi.Mux to prevent exposing third-party router dependencies directly to library consumers.

func (*Router) Delete

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

Delete adds the route `pattern` that matches a DELETE HTTP method to route handler `h`

func (*Router) Get

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

Get adds the route `pattern` that matches a GET HTTP method to route handler `h`

func (*Router) Group

func (r *Router) Group(pattern string, fn func(r *Router))

Group creates a new inline-router with a fresh middleware stack.

func (*Router) Patch

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

Patch adds the route `pattern` that matches a PATCH HTTP method to route handler `h`

func (*Router) Post

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

Post adds the route `pattern` that matches a POST HTTP method to route handler `h`

func (*Router) Put

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

Put adds the route `pattern` that matches a PUT HTTP method to route handler `h`

func (*Router) ServeHTTP

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

ServeHTTP implements the standard net/http.Handler interface.

func (*Router) Use

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

Use appends one or more middlewares onto the Router stack.

type Server

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

Server represents the Minato HTTP server instance, wrapping an internal http.Server and Router

func New

func New(opts ...Option) *Server

New creates a new Minato Server instance with the provided options.

func (*Server) Router

func (s *Server) Router() *Router

Router returns the underlying Minato Router for registering routes.

func (*Server) Run

func (s *Server) Run() error

Run starts the HTTP server, handles graceful shutdown on SIGINT and SIGTERM, and executes any registered closers before exiting.

func (*Server) Use

func (s *Server) Use(middlewares ...func(http.Handler) http.Handler)

Use registers global middleware that will be applied to all routes.