Docs Reference

Reference

The Reference section is the ground truth of Plumego.

If:

  • Core defines the framework’s promises
  • Concepts explain how it works
  • Architecture shows how to structure systems
  • Guides show how to solve problems
  • Patterns define long-term discipline
  • Advanced explores scale and evolution

Then Reference answers only one question:

“What exactly is available, and what does it do?”

Nothing more. Nothing less.

What This Section Is For

Reference documentation exists to:

  • Describe public APIs precisely
  • Define behavioral guarantees
  • Clarify edge cases
  • Remove ambiguity
  • Serve as a stable contract

This is the section you consult when:

  • You need exact behavior
  • You are implementing tooling
  • You are reviewing framework usage
  • You are debugging unexpected results
  • You want to know whether something is supported

What This Section Is Not

Reference is not:

  • A tutorial
  • A design guide
  • An opinion piece
  • A collection of examples
  • A best-practices document

If you are looking for how to use something well,
you are probably in the wrong section.

Stability and Compatibility

Everything documented here is:

  • Public
  • Supported
  • Intended for long-term use

Anything not documented here should be treated as:

  • Internal
  • Unstable
  • Subject to change without notice

If you depend on undocumented behavior,
you own the risk.

Reference vs Source Code

The Reference is stronger than the source code.

Why:

  • Source code changes
  • Reference defines intent
  • Bugs may exist, but contracts remain

If implementation diverges from Reference,
the implementation is wrong.

Structure of the Reference

The Reference is organized by core abstractions.

You will find precise documentation for:

  • App — application lifecycle and registration
  • Context — request-scoped API
  • Router — route registration and matching
  • Middleware — execution semantics
  • Handler — function contracts
  • Response Helpers — response-writing utilities
  • Errors — framework-level error behavior

Each page is intentionally narrow and factual.

Reading the Reference

You should read Reference pages:

  • Selectively
  • With a concrete question in mind
  • Alongside the source code if needed

Do not read the Reference end-to-end like a book.
Use it as a lookup table.

Reference and Versioning

The Reference documents behavior for the current major version of Plumego.

Breaking changes must:

  • Be reflected here
  • Be versioned
  • Be documented explicitly

If behavior changes without reference updates,
it is considered a bug.

Design Philosophy Behind the Reference

Plumego’s Reference follows three strict rules:

  1. Precision over completeness
    If behavior is ambiguous, it is clarified.

  2. Clarity over convenience
    No “it usually works like this”.

  3. Explicit absence is documented
    What Plumego does not provide is as important as what it does.

How This Section Evolves

As Plumego evolves:

  • New APIs appear here
  • Deprecated APIs are marked clearly
  • Removed APIs are documented in changelogs

The Reference grows slowly and deliberately.

Summary

The Reference section defines Plumego’s public surface area.

  • If it is here, you can rely on it
  • If it is not here, do not assume it exists
  • If something behaves differently, it is a bug

This section is the final authority on Plumego behavior.

Next

From here, continue with:

→ App — the Plumego application entry point
→ Context — request-scoped APIs
→ Router — route registration and matching
→ Middleware — execution contracts

Each page documents a single abstraction, precisely.

In this section

  • Public APIs
    Authoritative list and classification of Plumego public APIs, defining what is stable, supported, and safe to depend on.
  • Configuration Options
    Reference documentation for configuration options in Plumego: what the framework expects, what it ignores, and how configuration should be wired.
  • Middleware Signatures
    Formal definition of middleware function signatures in Plumego, including execution guarantees, constraints, and anti-patterns.
  • Error Codes and Error Semantics
    Reference documentation for error semantics in Plumego, clarifying what error codes exist, where they belong, and what the framework does not define.
  • A Minimal Service Framework That Returns to the Essence of Go
    Plumego is a minimal, composable, and highly controllable service framework built on the Go standard library, designed for long-term maintenance, low dependency, and engineering consistency.
  • Plumego vs Common Go Frameworks: Design Trade-offs Explained
    A comparison between Plumego and mainstream Go frameworks from the perspectives of design philosophy, engineering boundaries, dependency strategy, and long-term maintenance cost—explaining why they differ and which types of projects they best suit.
  • When You Should Not Use Plumego
    Plumego is not for every project. This article explains, from the perspectives of project stage, team structure, business goals, and risk models, when you should not choose Plumego.