Introducing Plumego — A Standard-Library-First Go HTTP Toolkit

Plumego is a small Go HTTP toolkit built around one clear idea:

Keep Go web services explicit, maintainable, and close to the standard library.

It is not designed to hide net/http.

It is designed to make net/http easier to organize, easier to maintain, and easier to grow into production services without adopting a heavy framework model.

Plumego is currently an early but increasingly structured open-source framework. Its direction is clear:

• standard library first
• zero external dependency by default
• ordinary http.Handler compatibility
• explicit application wiring
• narrow stable root packages
• optional capability extensions
• agent-friendly documentation, specs, and task structure

It is built for developers who like Go’s simplicity but still want a little more structure than raw http.ServeMux.

What Is Plumego?

Plumego is a standard-library-first Go HTTP toolkit.

At its core, Plumego keeps familiar Go primitives:

• handlers are ordinary func(http.ResponseWriter, *http.Request)
• middleware wraps http.Handler
• routing stays explicit
• server lifecycle remains visible
• application dependencies are wired in your own main package

This makes Plumego feel closer to Go itself than to a large application framework.

A minimal Plumego application looks like this:

package main

import (
	"log"
	"net/http"

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

func main() {
	cfg := core.DefaultConfig()
	cfg.Addr = ":8080"

	app := core.New(cfg, core.AppDependencies{})

	if err := app.Get("/ping", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		_ = contract.WriteResponse(w, r, http.StatusOK, map[string]string{
			"message": "pong",
		}, nil)
	})); err != nil {
		log.Fatal(err)
	}

	if err := app.Prepare(); err != nil {
		log.Fatal(err)
	}

	srv, err := app.Server()
	if err != nil {
		log.Fatal(err)
	}

	log.Fatal(srv.ListenAndServe())
}

The goal is not magic.

The goal is clarity.

Why Plumego?

Go already has a strong standard library.

For many services, net/http is enough.

But once a project grows, teams often need more structure around:

• routing
• middleware
• request metadata
• error responses
• lifecycle management
• health checks
• logging
• metrics
• security helpers
• storage contracts
• service layout
• documentation conventions

The common options are usually:

1. stay with raw net/http and manually assemble everything
2. adopt a larger web framework and accept its abstractions
3. build a private internal framework from scratch

Plumego tries to sit in the middle.

It provides enough structure to make services maintainable, while keeping the programming model close to the Go standard library.

Current Status

Plumego is currently in an early open-source stage, but it already has a meaningful structure.

The repository includes:

• core application package
• router package
• contract package
• middleware package
• security package
• health package
• log package
• metrics package
• store package
• reference service layouts
• documentation
• specs
• task definitions
• agent-oriented operating files
• optional capability packages under x/*

The framework is not positioned as a mature enterprise framework yet.

It is better understood as:

A carefully structured Go HTTP toolkit moving toward a stable v1-style developer experience.

At the current stage, Plumego is most valuable for developers who want to study, use, or contribute to a small framework with clear boundaries.

Design Philosophy

Plumego is built around several engineering principles.

1. Standard Library First

Plumego does not try to replace Go’s HTTP model.

It keeps standard library compatibility at the center.

That means developers can still use:

• http.Handler
• http.HandlerFunc
• http.Request
• http.ResponseWriter
• http.Server
• standard middleware composition
• standard Go testing patterns

This lowers adoption cost.

A developer who understands net/http can understand Plumego without learning an entirely new mental model.

2. Explicit Wiring

Plumego favors visible construction over hidden framework behavior.

Routes, middleware, dependencies, and lifecycle steps should be easy to find.

A service should not feel like it is controlled by invisible framework magic.

This matters because production systems are maintained over time.

When something breaks, developers need to know:

• where the route was registered
• which middleware is applied
• how dependencies are passed
• when the server is prepared
• how shutdown works
• how errors are shaped

Explicit wiring makes services easier to debug and easier to review.

3. Small Stable Surface

Plumego keeps its stable root surface intentionally narrow.

The core starting point is centered around packages such as:

core
router
contract
middleware

Additional capabilities exist, but they are not forced into the first learning path.

This is important.

A framework becomes hard to adopt when every feature appears mandatory.

Plumego’s model is:

Start small. Add capabilities only when the service needs them.

4. Optional Capabilities

Plumego separates stable root packages from optional capability families.

Optional areas may include:

• REST helpers
• tenant support
• gateway patterns
• WebSocket support
• AI provider integration
• messaging and webhooks
• RPC support
• observability extensions

These capabilities should extend the base service layout, not replace it.

This keeps the learning path stable.

A plain JSON API, a tenant-aware SaaS API, a gateway, and a WebSocket service should still share the same underlying service philosophy.

5. Agent-Friendly Maintenance

One of Plumego’s distinctive directions is agent-friendly engineering.

The repository is structured to make automated code agents easier to guide, review, and constrain.

This includes:

• docs/ for architecture and usage explanations
• specs/ for machine-checkable boundaries
• tasks/ for reviewable execution units
• reference/ for canonical wiring examples
• module-level metadata and conventions
• internal checks that enforce important boundaries

This direction is important in the current development environment.

As AI coding tools become common, repositories need more than source code.

They need structure that helps both humans and agents understand:

• what belongs where
• what should not change
• which modules own which responsibilities
• how to verify a change
• what a good implementation looks like

Plumego treats this as part of the framework’s engineering model.

Package Overview

Plumego is organized around clear package responsibilities.

core

The core package is responsible for application construction and lifecycle.

It handles:

• app configuration
• route registration
• middleware attachment
• server creation
• preparation before serving
• shutdown-related structure

This package is the main entry point for most services.

router

The router package provides routing behavior beyond raw http.ServeMux.

It supports service-friendly routing features such as:

• method-based route registration
• path parameters
• route groups
• metadata
• reverse URL generation

The router keeps handlers compatible with standard Go HTTP primitives.

contract

The contract package defines common response and error handling conventions.

It helps services return predictable responses.

This is especially useful for APIs where consistency matters.

A service should not return ten different error shapes from ten different handlers.

The contract package gives Plumego applications a canonical path for structured responses.

middleware

The middleware package provides middleware composition while keeping the familiar http.Handler shape.

Middleware should remain simple:

func Middleware(next http.Handler) http.Handler

This is one of the strongest parts of Go’s HTTP model.

Plumego keeps it.

security

The security package contains security-oriented helpers.

This area may include:

• authentication helpers
• JWT helpers
• password utilities
• security headers
• input safety helpers
• abuse guard primitives

Security is a practical concern for real services, but Plumego keeps these features modular.

A small service should not need to load a full security framework just to start.

store

The store package defines storage-related contracts and in-memory primitives.

It is not trying to become a full ORM.

Instead, it provides stable interfaces and simple primitives for common storage concerns, such as:

• cache
• key-value storage
• file storage
• database-oriented contracts
• idempotency primitives

This gives applications a common shape without forcing a single persistence model.

health

The health package focuses on health and readiness models.

Production services need health checks for:

• startup readiness
• dependency status
• container orchestration
• uptime monitoring
• deployment safety

Plumego treats health checks as a first-class operational concern.

log

The log package defines minimal logging interfaces.

The goal is to avoid forcing a heavy logging dependency while still giving services a consistent logging shape.

A good framework should not make logging decisions too early for the user.

It should define a useful boundary and let implementations evolve.

metrics

The metrics package provides minimal metrics contracts.

This may include:

• counters
• gauges
• timings
• collectors

Like logging, metrics should be easy to integrate without turning the base framework into an observability platform.

Plumego Compared with Raw net/http

Raw net/http is excellent.

But when applications grow, developers often need repeated patterns.

Plumego adds structure in areas where raw net/http leaves everything to the application.

Raw net/http:
- simple and powerful
- fully standard
- minimal abstraction
- manual routing patterns
- manual middleware conventions
- manual error shape
- manual lifecycle structure

Plumego:
- still standard-library compatible
- explicit route registration
- path parameter extraction
- route groups
- per-group middleware
- named routes and reverse URL generation
- structured response contracts
- request metadata helpers
- explicit prepare/server/shutdown lifecycle

Plumego does not claim that raw net/http is insufficient.

It claims that many real services benefit from a small layer of disciplined structure.

Plumego Compared with Larger Go Frameworks

There are already many mature Go web frameworks.

For example:

• Gin
• Echo
• Fiber
• Chi
• Go kit
• Buffalo
• Beego

These frameworks are useful and battle-tested.

Plumego is different in positioning.

It is not trying to be the biggest, fastest, or most feature-rich framework.

Its value is more specific:

A small, explicit, standard-library-first toolkit for maintainable Go services.

Compared with larger frameworks, Plumego emphasizes:

• less framework magic
• closer net/http compatibility
• narrower stable surface
• explicit application wiring
• optional extensions
• readable repository structure
• agent-friendly development workflow

This makes it more suitable for developers who want framework assistance without framework dominance.

Who Is Plumego For?

Plumego is suitable for several types of developers and teams.

Go Developers Who Like net/http

If you like the Go standard library but want better organization, Plumego is a natural fit.

It gives you routing, contracts, lifecycle, and service structure without asking you to abandon standard Go HTTP concepts.

Indie Developers Building Small Services

Indie developers often need simple APIs, internal dashboards, webhooks, and small SaaS backends.

For these cases, Plumego can provide enough structure without introducing heavy dependencies.

It is a good fit when you want:

• a small binary
• readable code
• simple deployment
• explicit control
• minimal moving parts

Teams Building Maintainable Internal Services

Internal services often do not need a massive framework.

They need consistency.

Plumego can help define:

• standard service layout
• routing conventions
• response contracts
• middleware patterns
• health check behavior
• logging and metrics boundaries

This helps teams avoid every service becoming a different custom framework.

Developers Exploring Agent-Friendly Engineering

Plumego is also interesting as an experiment in AI-era repository design.

Its docs/, specs/, tasks/, and reference layouts make it easier to guide code agents.

That makes Plumego useful not only as a web toolkit, but also as a repository design case study.

What Plumego Is Not

Plumego is intentionally not trying to be everything.

It Is Not a Heavy Full-Stack Framework

Plumego does not try to own:

• frontend rendering
• database migrations
• ORM models
• asset pipelines
• admin panels
• background workers
• deployment platforms

It focuses on HTTP service structure.

It Is Not a Magic Framework

Plumego does not aim to hide application wiring.

The application should remain visible.

The developer should understand how the service starts, how routes are registered, and how dependencies flow.

It Is Not Trying to Replace Every Go Framework

Gin, Echo, Fiber, Chi, and other frameworks already serve many developers well.

Plumego exists for developers who prefer a smaller, more explicit, standard-library-oriented approach.

Current Strengths

Plumego already has several strong foundations.

Clear Positioning

The project has a distinct identity:

standard-library-first, explicit, maintainable, agent-friendly.

This is more focused than simply saying “another Go web framework.”

Strong Compatibility Model

By keeping ordinary http.Handler and net/http compatibility central, Plumego reduces lock-in.

This matters for Go developers.

A good Go framework should feel like an extension of Go, not a replacement for Go.

Modular Package Boundaries

The package structure is understandable.

Core packages handle stable responsibilities.

Optional packages can grow without making the base path heavier.

This is a healthy framework direction.

Documentation-Oriented Repository

Plumego already includes documentation, reference layouts, specs, and tasks.

This makes the project easier to review and easier to evolve.

For an open-source framework, documentation is not decoration.

It is part of the product.

Agent-Friendly Direction

The agent-friendly approach is a meaningful differentiator.

In the AI coding era, frameworks and repositories need to be easier for automated agents to inspect, modify, and validate.

Plumego is exploring this direction directly.

Current Challenges

Plumego is still early.

That means it also faces several challenges.

1. API Stability

A framework needs a stable public surface.

Plumego should continue to clarify:

• which packages are stable
• which packages are experimental
• which APIs are guaranteed
• which APIs may change
• how semantic versioning will be handled

This is important for adoption.

Developers need to know what they can depend on.

2. Real-World Examples

Framework adoption depends heavily on examples.

Plumego should continue building reference applications such as:

• plain JSON API
• CRUD REST service
• authentication example
• tenant-aware SaaS service
• WebSocket service
• webhook receiver
• API gateway
• observability-enabled service

Examples turn framework ideas into practical trust.

3. Documentation Depth

The project already has documentation structure, but framework docs need continuous improvement.

Useful docs should include:

• 5-minute quick start
• 30-minute service tutorial
• production layout guide
• middleware guide
• routing guide
• error handling guide
• testing guide
• deployment guide
• comparison with raw net/http
• migration path from small services

Good documentation is one of the most important features of a framework.

4. Ecosystem Trust

Go developers are cautious about web frameworks.

To build trust, Plumego needs:

• stable releases
• clear changelog
• benchmarks
• compatibility promises
• security policy
• contribution guide
• examples
• tests
• production-oriented references

Trust grows slowly.

That is normal.

5. Scope Control

The biggest risk for a small framework is becoming too large.

Plumego should continue to protect its core identity.

The root path should stay small.

Optional features should remain optional.

The framework should avoid becoming a mixed collection of unrelated utilities.

Recommended Near-Term Roadmap

A practical next-stage roadmap for Plumego could look like this.

v0.x — Solidify the Foundation

Focus:

• stabilize core package APIs
• improve router behavior and documentation
• complete standard service reference
• document middleware conventions
• improve structured error examples
• add more lifecycle examples
• keep compatibility with standard net/http

Goal:

Make the smallest Plumego service feel obvious and reliable.

v0.x+1 — Production Readiness

Focus:

• health and readiness examples
• graceful shutdown examples
• logging integration guide
• metrics integration guide
• security headers guide
• JWT and password examples
• request ID and tracing examples
• rate limiting examples
• deployment guide

Goal:

Make Plumego feel safe for small production services.

v0.x+2 — Reference Applications

Focus:

• REST API example
• SaaS-style tenant API example
• webhook receiver example
• WebSocket example
• gateway example
• observability example
• testing example

Goal:

Show developers how to build real services, not just toy examples.

v1.0 — Stable Core Contract

Focus:

• freeze stable root packages
• document compatibility guarantees
• clearly mark experimental packages
• publish migration guide
• provide release notes
• define contribution model
• complete public documentation site

Goal:

Make Plumego safe to depend on.

Suggested Product Positioning

Plumego should avoid generic positioning like:

A lightweight Go web framework.

That description is too common.

A stronger positioning would be:

Plumego is a standard-library-first Go HTTP toolkit for explicit, maintainable, agent-friendly services.

This positioning highlights what makes Plumego different:

• standard-library-first
• explicit
• maintainable
• agent-friendly

It also avoids overclaiming.

Plumego does not need to be the biggest Go framework.

It needs to be the clearest one for its target users.

Suggested Website Message

A good Plumego landing page could start like this:

Plumego is a small Go HTTP toolkit built on the standard library.

It keeps net/http compatibility at the center, gives your services a clear structure, and avoids heavy framework magic.

Use ordinary handlers.
Compose ordinary middleware.
Wire dependencies explicitly.
Grow from a small API to a production service without losing clarity.

This message is simple, accurate, and aligned with the project.

Practical Use Cases

Plumego is especially suitable for these scenarios.

Small JSON APIs

A small API often needs:

• routing
• response helpers
• structured errors
• middleware
• graceful startup and shutdown
• health checks

Plumego fits this use case well.

Internal Tools

Internal tools benefit from simple deployment and readable code.

Plumego can support:

• admin APIs
• internal dashboards
• webhook handlers
• automation services
• backend control panels

SaaS Backends

For small SaaS backends, Plumego can provide a service foundation around:

• authentication
• tenant context
• API keys
• usage tracking
• health checks
• structured logging
• metrics

The key is to keep the architecture explicit.

API Gateways and Proxies

Plumego’s standard-library-first model can fit lightweight gateway services where developers need control over:

• request routing
• middleware
• headers
• reverse proxy behavior
• observability
• authentication

Agent-Built Services

Because Plumego emphasizes specs, tasks, docs, and canonical reference layouts, it can become a good foundation for AI-assisted service generation.

This is a promising direction.

A framework that is easy for humans and agents to understand may become more valuable in the next generation of development workflows.

Engineering Principle

The core engineering principle behind Plumego can be summarized as:

Structure should make Go services easier to understand, not harder to escape.

This principle matters.

A framework should not trap developers.

It should provide conventions while still allowing escape hatches.

It should make common paths easier without hiding the underlying system.

Plumego’s use of ordinary Go HTTP primitives supports this philosophy.

Why Plumego Matters Now

The Go ecosystem is mature.

There are already many frameworks, routers, and service toolkits.

So why build another one?

Because the development environment is changing.

Modern services need to be:

• simple enough for small teams
• explicit enough for long-term maintenance
• structured enough for AI coding agents
• compatible enough with existing Go practices
• documented enough for safe automated modification

Plumego is interesting because it is not just another router.

It is an attempt to combine:

• Go standard library discipline
• small-framework ergonomics
• production service structure
• AI-era repository maintainability

That combination makes the project worth watching.

Current Recommendation

At its current stage, Plumego is best used in these ways:

• as a learning project for standard-library-first framework design
• as a foundation for small Go HTTP services
• as a reference for agent-friendly repository structure
• as an experimental toolkit for explicit service architecture
• as a candidate framework for internal APIs and developer tools

For high-risk production systems, teams should still evaluate API stability, test coverage, documentation completeness, and release guarantees carefully.

But for developers who like the direction, Plumego is already a useful and thoughtful project.

Final Thoughts

Plumego is still young, but its direction is clear.

It does not try to impress developers with complexity.

It tries to preserve what makes Go attractive:

• simple primitives
• explicit code
• readable services
• predictable behavior
• small operational surface

At the same time, it adds the structure that real services need:

• routing
• middleware
• contracts
• lifecycle
• health
• logging
• metrics
• security helpers
• reference layouts
• agent-friendly project organization

That makes Plumego more than a minimal router.

It is a calm, standard-library-first toolkit for building Go services that remain understandable as they grow.

Plumego is early.

But it has a strong foundation and a clear product philosophy:

Keep Go services explicit. Keep the framework small. Make maintenance easier for humans and agents.

That is a direction worth building.

— The Birdor Team