Docs Your First Request

Your First Request

At this point, you have:

  • A running Plumego server
  • A minimal project layout
  • A working HTTP endpoint

This document focuses on a single question:

What actually happens when a request hits a Plumego service?

Understanding this now will make every later concept easier.

The Request We Will Trace

We start with the same minimal route:

app.GET("/", func(ctx *plumego.Context) {
	ctx.String(http.StatusOK, "Hello, Plumego")
})

And the request:

curl http://localhost:8080/

Everything that follows happens because of this single call.

Step 1: The Request Enters net/http

Plumego does not replace Go’s HTTP server.

When you call:

app.Run(":8080")

Plumego internally starts a standard http.Server.

This means:

  • Requests are accepted by net/http
  • Connection handling follows Go’s standard behavior
  • Timeouts, cancellation, and context propagation behave as documented by Go

Plumego sits on top of, not instead of, the standard library.

Step 2: The Router Matches the Path

Once the request is accepted, Plumego’s router:

  • Examines the HTTP method (GET)
  • Matches the request path (/)
  • Selects the corresponding handler

There is no reflection, annotation scanning, or dynamic routing.

Only routes that were explicitly registered can be matched.

If no route matches, Plumego returns a standard 404 response.

Step 3: Middleware (If Any) Runs

In the minimal example, no middleware is registered.

In a real application, this is where cross-cutting concerns would run:

  • Logging
  • Authentication
  • Tracing
  • Panic recovery

Middleware execution is:

  • Linear
  • Ordered
  • Explicit

Nothing runs unless you register it.

Step 4: The Context Is Created

Before your handler is called, Plumego creates a Context object.

This context:

  • Wraps the underlying http.Request and http.ResponseWriter
  • Embeds context.Context
  • Exists only for the lifetime of the request

The context is request-scoped and never reused.

This guarantees isolation between requests.

Step 5: The Handler Is Invoked

Your handler is called with the context:

func(ctx *plumego.Context) {
	ctx.String(http.StatusOK, "Hello, Plumego")
}

At this point:

  • You control the response
  • You can read request data
  • You can write headers and body

There is no hidden post-processing.

What your handler does is what the client receives.

Step 6: The Response Is Written

When you call:

ctx.String(http.StatusOK, "Hello, Plumego")

Plumego:

  • Sets the HTTP status code
  • Writes the response body
  • Finalizes the response

Once the handler returns, the request lifecycle is complete.

A Complete Mental Model

The entire flow can be summarized as:

Client
  ↓
net/http Server
  ↓
Plumego Router
  ↓
Middleware Chain (optional)
  ↓
Context Creation
  ↓
Handler Execution
  ↓
Response Written
  ↓
Connection Closed or Reused

There are no hidden stages.

If you understand this diagram, you understand Plumego’s core execution model.

What Plumego Does Not Do Automatically

It is important to notice what did not happen:

  • No automatic request parsing
  • No automatic JSON serialization
  • No global error handling
  • No implicit logging
  • No background processing

Plumego does not assume what kind of service you are building.

Every additional behavior must be explicitly added.

Why This Explicit Flow Matters

This explicit request flow provides several benefits:

  • Debugging becomes straightforward
  • Performance characteristics are predictable
  • Behavior does not change unexpectedly
  • Engineers can reason about failure modes

This is foundational to Plumego’s long-term maintainability goals.

A Common Misconception

New users sometimes expect Plumego to “do more” automatically.

This is a misunderstanding.

Plumego’s role is to:

Define where things happen — not to decide what happens.

Once this is clear, the framework becomes much easier to use correctly.

Summary

In your first request, you saw that:

  • Plumego relies on Go’s standard HTTP server
  • Routing and middleware are explicit
  • Context is request-scoped and predictable
  • Handlers fully control the response
  • Nothing happens unless you ask for it

This is not accidental minimalism.

It is the foundation on which the rest of Plumego is built.

Next

You have completed the Getting Started section.

The next step is to understand Plumego’s core abstractions in depth.

Continue with:

→ Concepts / Request Lifecycle

This is where Plumego’s mental model becomes complete.