All jobs

Add Request Timeouts to a Gin API

Yes. An agent replaces r.Run with an http.Server that has read, write and idle timeouts, adds a per-request deadline middleware to your Gin API, tests it, in a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent reads how the server is started. In an API shaped like gothinkster/golang-gin-realworld-example-app, go.mod says go 1.21 with gin v1.10.0, gorm v1.25.12, the sqlite driver v1.5.7, golang-jwt v5.2.1 and testify v1.10.0. hello.go calls common.Init() to open the SQLite file named by DB_PATH, runs the GORM auto-migrations, builds gin.Default(), turns off RedirectTrailingSlash, mounts the /api groups behind users.AuthMiddleware, adds /api/ping and then calls r.Run(":" + port) with PORT from the environment or 8080. Run is a thin wrapper over http.ListenAndServe, which builds an http.Server with no ReadHeaderTimeout, ReadTimeout, WriteTimeout or IdleTimeout, so a client that sends headers one byte at a time, or opens a keep-alive connection and goes quiet, holds a goroutine and a file descriptor for as long as it likes. common/database.go sets SetMaxIdleConns(10) on the pool and nothing else, and no handler in users/routers.go or articles/routers.go reads a deadline from its context.

Two changes follow, both in the standard library because go.mod carries no gin-contrib packages beyond gin's own. In hello.go the agent replaces r.Run with an explicit http.Server whose Addr is the same port and whose Handler is the engine, with ReadHeaderTimeout, ReadTimeout, WriteTimeout and IdleTimeout read from new environment variables with defaults, listed in .env.example and in the readme's environment table next to PORT, GIN_MODE and DB_PATH. ListenAndServe is called on that server and the log.Fatal on error stays as it was. The second change is a per-request deadline: a middleware in common/ that wraps c.Request.Context() with context.WithTimeout, swaps it into the request, and runs the handler in a goroutine so that when the deadline passes first it can still answer with a JSON body in the errors shape common.NewError produces and a 503 or 504 status, instead of the empty reply a WriteTimeout alone leaves behind. It is attached to the /api group in hello.go so the ping route and the RealWorld routes share it.

A deadline only helps if the work notices it, so the agent threads the request context into the queries that can run long. The handlers reach GORM through common.GetDB() with no context today; the agent passes db.WithContext(ctx) in the article list and feed paths, where a slow query would otherwise keep running after the client has gone, and leaves the primary-key lookups alone. Tests follow users/unit_test.go, which uses httptest, testify's assert and common.TestDBInit(): a handler that sleeps past a short deadline answers the timeout status and body, a fast handler answers unchanged, and the server timeouts are checked by starting the configured http.Server on a free port, opening a raw TCP connection, sending nothing, and reading EOF after ReadHeaderTimeout.

Then it runs what .github/workflows/ci.yml runs: bash ./scripts/gofmt.sh, bash ./scripts/coverage.sh, which tests every package with -covermode=atomic and merges the profiles into coverage.out, and golangci-lint v1.61 with the staticcheck, unused and misspell linters .golangci.yml enables. It also runs scripts/run-api-tests.sh, which deletes data/gorm.db, builds hello.go, starts it on PORT=8080 and runs the RealWorld Postman collection, so the branch shows the register, login, article and comment flow still passing under the new server.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add request timeouts to this Gin API. Read go.mod, hello.go, common/database.go, common/utils.go, users/middlewares.go, users/routers.go, articles/routers.go, users/unit_test.go, .env.example, readme.md, .golangci.yml, the scripts under scripts/ and the workflow under .github/workflows first. Replace r.Run with an explicit http.Server that keeps the same port and sets ReadHeaderTimeout, ReadTimeout, WriteTimeout and IdleTimeout from environment variables with sensible defaults, documented in .env.example and the readme's environment table. Add a per-request deadline middleware using only the standard library, attached to the /api group, that answers with a JSON error in the shape common.NewError produces when the deadline passes before the handler has written. Thread the request context into the GORM queries that can run long. Write tests in the style of the existing unit tests for a slow handler, a fast handler and the server's header timeout using a raw TCP connection. Run gofmt, the coverage script, golangci-lint and scripts/run-api-tests.sh as CI does, and open a pull request that explains the values chosen and quotes the test output.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

What comes back is a pull request on its own branch that changes hello.go, adds a middleware file and its test under common/, extends .env.example and the readme's environment table, and touches the article queries that now take a context. No route, serializer or validator changes, and go.mod gains no dependency.

The description explains the four server timeouts and the per-request deadline, says which values it chose and why the per-request deadline is shorter than WriteTimeout, and quotes the test output, the gofmt and lint runs and the tail of scripts/run-api-tests.sh from the sandbox.

Before merging, a reviewer sets the production values (an upload or a report route may need a longer deadline than the RealWorld endpoints), decides whether the timeout answer should be 503 or 504, and whether the explicit http.Server should now also get a signal-driven Shutdown. Each of those is a follow-up on the same session.

Run it on every Go service started with r.Run

This is a change to hand off from the terminal: one POST /o/{org}/sessions with this prompt and the repository in resources, and the run reads the server setup, writes the middleware, holds a socket open to prove the header timeout and opens the pull request on its own. The sandbox parks with its disk when the turn ends, so make the deadline per route instead of per group as a follow-up wakes it with the module cache and the branch in place.

A team with several Go services sends the same body once per repository, one run each, and each run reads that service's own entry point and environment file. Give the API key a webhook_url and Rush posts run.completed or run.failed with the session_url when each turn ends. Send a request_id with each body so a retried POST returns the run it already started.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

Timeouts are the change everyone agrees on and nobody schedules, because proving them means holding a socket open on purpose and watching the server drop it. The agent does that in its own sandbox with a raw TCP connection and a sleeping handler, and the pull request carries the test output rather than a promise.

The record shows the reasoning as well as the result: the transcript has the agent reading that r.Run is ListenAndServe underneath, choosing the standard library over a contrib package to match go.mod, and running the Postman collection to make sure the RealWorld flow still passes. A reviewer who wants different defaults says so and the parked sandbox changes the constants.

Frequently asked questions

Why not gin-contrib/timeout?

It works and the agent will use it if you ask, but go.mod has no gin-contrib packages and the per-request deadline needs only context.WithTimeout, a goroutine and a select. Fewer dependencies is the convention the repository already follows.

What does a client see when the deadline passes?

A JSON body in the same errors shape common.NewError produces, with a 503 or 504 status, instead of a dropped connection. If the handler had already started writing, the response cannot be replaced and the connection closes when WriteTimeout fires.

Will long-running routes break?

Only if they are slower than the deadline. The pull request lists the values in .env.example so they can be raised per environment, and the middleware is attached to the group, so a route that needs more can be registered outside it or wrapped with its own deadline.

Does the SQLite database honour the context?

GORM passes the context to database/sql, which cancels the query on drivers that support it. The agent threads the context into the article list and feed queries and keeps the quick primary-key lookups unchanged, and the tests cover the handler-level behaviour either way.

Does this add graceful shutdown?

Not in this pull request. Replacing r.Run with an http.Server is the prerequisite, and a follow-up on the same session can add signal handling and Shutdown with a drain period.

More Gin jobs

The same job on other stacks

Keep reading