Docs Router

Router

The router is responsible for dispatching an incoming HTTP request to the correct handler.

In Plumego, the router is intentionally simple.
It exists to answer one question — and only one question:

Which handler should handle this request?

Everything else belongs elsewhere.

Router as a Deterministic Dispatcher

Plumego’s router is designed to be:

  • Deterministic
  • Explicit
  • Easy to reason about

Routing behavior is fully determined by:

  • HTTP method
  • Request path
  • The order in which routes are registered

There is no implicit discovery, reflection, or annotation-based configuration.

If a route exists, it is because it was explicitly registered in code.

Route Registration Is Explicit

Routes are registered directly on the application:

app.GET("/health", healthHandler)
app.POST("/users", createUserHandler)

Key properties:

  • Registration happens at startup
  • Routes cannot be added dynamically at runtime
  • The set of routes is fixed once the server starts

This makes the exposed API surface fully predictable.

Method-Based Dispatch

Plumego routes are always bound to an HTTP method.

This means:

  • GET /users and POST /users are distinct routes
  • Method mismatch results in a non-match
  • Handlers do not need to inspect HTTP methods manually

Method-based dispatch keeps handlers focused on their intended semantics.

Path Matching Model

Plumego matches request paths against registered patterns.

Important characteristics:

  • Matching is deterministic
  • Only registered patterns are considered
  • Ambiguous routes are resolved by registration order

Plumego does not attempt to infer intent.

If two routes overlap, the developer is responsible for resolving the ambiguity.

Route Parameters

Routes may include path parameters:

app.GET("/users/:id", getUserHandler)

Path parameters:

  • Are extracted from the URL path
  • Are available via the request context
  • Exist only for the lifetime of the request

They should be treated as input, not as validated domain values.

Validation belongs in handlers or application logic.

Router and Middleware Interaction

Routing always occurs before middleware execution.

This has important consequences:

  • Middleware can assume a matched route exists
  • Authorization can be route-aware
  • Middleware does not need to inspect raw paths

Global middleware applies to all routes,
but route-specific middleware may be layered explicitly if desired.

Router Does Not Perform Business Logic

The router does not:

  • Validate input
  • Perform authorization
  • Transform request data
  • Handle errors beyond routing failures

Its responsibility ends once the correct handler is selected.

This strict separation keeps routing behavior stable and easy to debug.

404 and Non-Matching Routes

If no route matches:

  • Plumego returns a standard 404 response
  • No middleware or handler is executed
  • The request lifecycle ends immediately

This behavior is consistent and predictable.

Plumego does not attempt to guess intent or suggest alternatives.

Why Plumego Avoids Complex Routing Features

Some frameworks offer:

  • Regex-heavy routing
  • Automatic versioning
  • Subdomain-based dispatch
  • Dynamic route mutation

Plumego avoids these features intentionally.

Why

  • Complex routing logic is difficult to reason about
  • It often hides API surface changes
  • It increases the cost of refactoring

Plumego favors clarity over expressiveness at the routing level.

Router as Part of the Application Boundary

The router belongs to the framework edge.

Domain and application logic should never:

  • Depend on router internals
  • Inspect routing decisions
  • Modify routing behavior

This ensures that routing can change without affecting core logic.

Common Mistakes

Using the Router as a Versioning Mechanism

Avoid encoding business versioning deeply into routes without clear intent.

Versioning is an architectural concern, not a routing trick.

Overloading Route Parameters

Path parameters should represent identity, not complex state.

Prefer request bodies or query parameters for rich input.

Summary

In Plumego, the router is:

  • Explicit
  • Deterministic
  • Minimal by design

It matches requests to handlers and nothing more.

This simplicity is what allows the rest of the system to remain predictable.

Next

With routing understood, the final core concept is:

→ Error Model

This explains how Plumego expects errors to be represented, propagated, and handled.