PlumeGo lab review: using reference services to test HTTP boundaries

The lab question

Framework boundaries are easy to describe in a small package and harder to preserve when an application needs routes, responses, middleware, operational checks and use-case-specific wiring. PlumeGo’s public repository separates core, router, contract and middleware-oriented modules from reference and examples. The lab question is whether those runnable surfaces make the kernel easier to inspect under real application pressure. Inspect the PlumeGo repository ↗.

Reference services as a boundary probe

A reference service should not absorb every optional capability into the core. Its job is to exercise a stable route from application composition to a familiar net/http handler while keeping the owning module visible.

flowchart LR
  UseCase[Bounded use case] --> Core[core composition]
  Core --> Router[router registration]
  Router --> Middleware[middleware order]
  Middleware --> Handler[net/http handler]
  Handler --> Contract[contract response]
  Reference[reference service] -. exercises .-> Core
  Examples[examples/] -. compares .-> Router

This map follows the public module names and reference directories rather than inventing a hidden framework lifecycle. A reviewer can begin at the use case, find application composition, then trace routing and response handling in ordinary Go shapes. The reference is evidence that the route can be assembled, not a separate implementation model.

What the public artifacts let us inspect

The point of this distribution is not to multiply folders. It is to preserve a useful question at every step: _which package owns the next change?_ If a service needs a response convention, contract is a visible candidate. If it needs application assembly, core is a visible candidate. If it needs a particular example, that example can demonstrate the choice without turning it into a kernel requirement.

An intentionally ordinary service shape

The lab favors familiar Go interfaces because recognizability is part of inspectability. The following is a small illustrative composition pattern; exact APIs and release notes remain maintained in the repository documentation.

// Illustrative boundary: compose the application, register a route,
// then retain an ordinary net/http handler at the transport edge.
app := core.New(config, dependencies)

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

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

The value is not that the example is short. It is that the route, response convention and preparation step have discernible homes. A reader does not need to decode generated wiring before deciding how an HTTP concern enters the application.

What this lab does not establish

Reference services cannot prove every extension is stable, nor should they. A public repository may expose a small standard-library-first path while other modules remain optional or still under evaluation. Treating every reference implementation as a promise would erase the maturity distinction that makes a small interface credible.

Instead, the lab helps maintain a working discipline: extensions should declare their maturity, use cases should reveal the pressure they apply, and the core path should only grow when the new boundary remains both useful and inspectable.

Conclusion

PlumeGo’s reference services make architecture review concrete. They connect a bounded use case to composition, routing and response ownership in a form that can run, be inspected and be compared with the public module map. That makes the reference track a practical laboratory for testing whether an HTTP kernel stays explicit when it meets actual service work.

Continue from the [PlumeGo reference services Lab record](/labs/plumego-reference-services) to the linked source artifacts and implementation notes.

Reproduction protocol

The hypothesis is narrow: a reference service can exercise routing, response contracts and application lifecycle without importing optional extension families into its canonical application path. This is not a throughput or production-readiness claim.

Use Go 1.26.0 and the fixed source revision listed below. From the repository root:

cd reference/standard-service
go test ./...

This submodule already replaces the PlumeGo module with the parent checkout, so the test uses the inspected source. Inspect internal/app/routes.go, then follow the handlers into the item service and repository interface. Existing acceptance tests cover route registration, real server requests, shutdown, body limits, configured CORS and readiness. Their presence alone is not evidence of passing; the execution result is recorded separately below.

The [first-service guide](/engineering/plumego-first-service) additionally reproduces a 200 JSON response and a 404 using an ordinary HTTP client. That small round trip is complementary evidence, not a substitute for the reference application's tests.

Limits and revisit trigger

The canonical reference uses an in-memory item store. Passing its tests does not establish database durability, extension compatibility, deployment hardening or behavior under load. No competing framework benchmark or failure-injection campaign was run for this review. Revisit when the fixed source changes its route table, response contract, lifecycle behavior or dependency boundary; rerun the same commands before updating the conclusion.

Observed result

On September 21, 2026, go test ./... passed in the app, config, domain/item and handler packages; the root package had no test files. Together with source inspection, this supports the canonical path at the fixed revision. It does not prove every optional reference or extension works.

Evidence baseline

Source structure and API names were reviewed on September 20, 2026 against spcent/plumego at 2113d375a28a ↗. This is a source review, not a runtime or performance certification. Code fragments illustrate ownership boundaries; they are not complete runnable programs.