stdlib-only · zero external deps · v1.1.0

stdlib-first Go HTTP toolkit · 9 stable roots · no third-party imports

Go HTTP your agent and your team can both read.

Route registration, middleware order, and dependency wiring live in one explicit file — visible in every code review. Machine-readable specs give AI coding agents the same operating model as your senior reviewers.

Go 1.24+ · stdlib-only kernelnet/http compatiblemachine-readable specsagent-ready control plane

Quickstart

Running in under two minutes.

Install Plumego, write one handler, run the service, and verify the canonical JSON response. Use the reference app when you want the complete service shape.

Read the Reference App Guide
run reference app
cd reference/standard-service && go run .
main.go
package main

import (
    "log"
    "net/http"

    "github.com/spcent/plumego/contract"
    "github.com/spcent/plumego/core"
)

func main() {
    app := core.New(core.DefaultConfig(), core.AppDependencies{})

    _ = app.Get("/ping", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        _ = contract.WriteResponse(w, r, http.StatusOK, map[string]string{"status": "ok"}, nil)
    }))

    _ = app.Prepare()
    srv, _ := app.Server()
    log.Fatal(srv.ListenAndServe())
}
verify
$ go mod init myservice
$ go get github.com/spcent/plumego@latest
$ go run .

$ curl localhost:8080/ping
{"data":{"status":"ok"}}

Code review

The difference shows in code review.

When route ownership and middleware order are visible in one place, reviewers can understand service behavior without opening every package or reading framework internals.

01

Routes split across packages

A reviewer sees registrations, but not the full public surface or the middleware chain.
main.go
func main() {
    mux := http.NewServeMux()

    items.Register(mux)   // paths? middleware?
    users.Register(mux)   // must open each package
    orders.Register(mux)  // to find out

    http.ListenAndServe(addr, mux)
}
02

Plumego: one file, one contract

The route map, middleware order, and response contract stay reviewable at the transport boundary.
internal/app/routes.go
func (a *App) Routes() http.Handler {
    r := router.New()

    r.Use(middleware.RequestID)
    r.Use(middleware.Logger(a.log))

    r.Get("/api/items", a.items.List)
    r.Get("/api/orders", a.orders.List)
    r.Get("/api/users", a.users.List)

    return r
}

Canonical path

Start from one canonical request path.

Begin with reference/standard-service. Read startup, wiring, and routes in order before expanding into deeper boundaries.

  1. 01Read main.go firstConfirm where the application starts and how the server is assembled.
  2. 02Open internal/app/app.goInspect the app-local constructor and keep dependencies explicit.
  3. 03Finish in internal/app/routes.goCheck which paths are public, what middleware runs, and where transport control ends.

Module maturity

Know exactly what you can rely on.

Three tiers, one release posture. Stable roots stay narrow; extensions declare where they are on the maturity curve so teams can adopt with eyes open.

01

Compatibility guaranteed

9 stable roots
core · router · contract · middleware · security · store · health · log · metrics — kernel packages that import only the Go standard library.
02

API frozen between refs

7 beta extensions
Extension families whose public surface has stabilized while they still collect production feedback.
03

Evaluate before adopting

7 experimental families
Fast-moving capability work in x/*. Expect breaking changes until a family graduates to beta.

What changes

What this approach changes.

The goal is not more abstraction. It is keeping important structure visible after the codebase stops being small.

The point is a toolkit that still reads clearly after the codebase grows, whether the next reviewer is a human engineer or a code agent.

01

Routes, middleware, and dependencies stay in code

visible wiring
A new engineer can trace startup, middleware, and dependency entry points without reading framework source.
02

The stable surface stays intentionally small

narrow surface
Core modules carry compatibility guarantees while fast-moving capabilities start in extension families.
03

Know what is safe to adopt before committing

adoption signals
Teams can distinguish a stable baseline from an experimental family before production adoption.
04

Change ownership stays easy to classify

repo clarity
Humans and code agents share the same language for middleware, handlers, modules, and task boundaries.
05

net/http compatible: no framework lock-in

stdlib first
Handlers remain ordinary func(http.ResponseWriter, *http.Request) values that work with stdlib tooling.
06

One reference service shape for the whole team

canonical shape
reference/standard-service defines the default wiring pattern instead of forcing every service to invent one.

Next pages

Choose the next page by question, not by package.

Use the Plumego site as the canonical owner for deeper docs, architecture, agent workflow, examples, release maturity, and FAQ answers.

01

Why Plumego

fit
Start here when the question is whether Plumego fits your team, service shape, and review expectations.
02

Architecture

layout
Module tiers, stable roots, and how transport, contract, and extension families fit together.
03

Agent Workflow

agent-first
How machine-readable specs route AI coding agents to the right module and enforce boundaries in CI.
04

Examples

examples
Walk through runnable services and recipes for request flow, middleware order, and extensions.
05

Releases

maturity
Check whether a module is stable enough to adopt in production right now.
06

FAQ

questions
Find direct answers for databases, JWT auth, framework comparisons, errors, and production config.

Read the docs, run the reference app, then expand only when the boundary is clear.

Plumego works best when teams start from the default path, check module maturity early, and branch into deeper boundaries only after ownership is obvious.