Go Version Status License

Plumego is a small Go HTTP toolkit built on the standard library, keeping net/http compatibility at its center: handlers are ordinary func(http.ResponseWriter, *http.Request), middleware wraps http.Handler, and application wiring stays explicit in your own main package.

The stable surface is intentionally narrow. Start with core, router, contract, and middleware; add security, store, health, log, and metrics only when those responsibilities are needed.

main.go:

package main
import (
	"log"
	"net/http"
	"github.com/spcent/plumego"
	"github.com/spcent/plumego/contract"
)
func main() {
	app := plumego.New()
	app.Get("/ping", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		_ = contract.WriteResponse(w, r, http.StatusOK, map[string]string{"message": "pong"}, nil)
	}))
	log.Fatal(http.ListenAndServe(":8080", app))
}

Run:

go mod init example.com/hello
go get github.com/spcent/plumego@latest
go run main.go

Open http://localhost:8080/ping. For a production-style layout, read reference/standard-service next.

For non-default address, timeouts, or TLS:

cfg := plumego.DefaultConfig()
cfg.Addr = ":9090"
app := plumego.NewWithConfig(cfg)

For production wiring with explicit logger injection, use core.New directly — see docs/start/getting-started.md.

All paths keep reference/standard-service as the base layout; extensions are explicit additions, not alternate bootstraps.

For Go services that need more structure than raw http.ServeMux without taking on a large framework model.

Optional capability families live under x/* — additions to the stable root path, not alternate layouts.

The nine packages listed above are stable roots carrying a full v1 compatibility guarantee: signatures, package names, and behaviour are frozen for the v1.x release series.

Seven x/* extension families are beta — stable across cited release refs and suitable for production adoption with minor caveats: x/frontend, x/gateway, x/messaging, x/observability, x/rest, x/tenant, and x/websocket.

All remaining x/* extensions are experimental: APIs may change in any minor version without notice. Do not use them in production services without explicit project-level stabilization.

See docs/reference/extension-stability-policy.md for the full compatibility policy, SemVer expectations, and promotion criteria.

Plumego is maintained with an agent-first control plane: docs/ explains the architecture, specs/ records machine-checkable boundaries, tasks/ defines reviewable execution units, and reference/ shows canonical wiring. Checks under internal/checks/ enforce key boundaries locally and in CI, so automated changes produce reviewable evidence instead of implicit convention. See docs/concepts/agent-first.md for the model and adoption path, and docs/operations/agent-first-operating-reference.md for the internal operating reference.

• docs/start/getting-started.md — smallest runnable walkthrough.
• reference/standard-service — canonical app layout.
• docs/reference/reference-apps.md — guide to choosing a reference application.
• docs/reference/canonical-style-guide.md — handler, middleware, routing, DI conventions.
• docs/modules — package-specific primers.
• docs/start/adoption-path.md — 5-minute, 30-minute, 1-day adoption path.
• docs/start/troubleshooting.md — route freeze, middleware order, JWT errors, lifecycle issues.
• docs/evidence/benchmarks/README.md — performance vs Chi, Gin, Echo.