# Add Graceful Shutdown to an Echo App

Yes. An agent makes your Echo server stop on SIGTERM, finish in-flight requests under a deadline, close the database, and opens a PR with a test.

[Run this on Rush](https://cloud.getrush.ai/run/add-graceful-shutdown/echo/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent starts with how the server is started today, because that line is the whole problem. In an Echo API like xesina/golang-echo-realworld-example-app, `go.mod` names `github.com/labstack/echo/v4` v4.1.16 and `github.com/jinzhu/gorm` v1.9.8 on a `go 1.18` directive, and `main.go` ends with `r.Logger.Fatal(r.Start("127.0.0.1:8585"))`. `Start` blocks until the listener fails, and nothing catches `SIGTERM`, so the Go runtime ends the process the moment the signal arrives: a request in the middle of a GORM write to `./realworld.db` is cut off, and the SQLite handle `db.New()` opened is never closed. `router/router.go` builds the `*echo.Echo` with `RemoveTrailingSlash`, the request logger and CORS, `handler/routes.go` registers the `/api` routes under JWT middleware, and `main.go` also mounts `/swagger/*` from the committed `docs/` package.

The agent then checks what sends the signal. `Dockerfile` ends with `CMD ["./golang-echo-realworld-example-app"]` in an `alpine` image with no init process, so the binary is PID 1 and `docker stop` delivers `SIGTERM` straight to it; `.github/workflows/go.yml` runs `go build -v ./...` and `go test -v ./...` on Go 1.18, and `Makefile` builds and tests with `-race`. It notes in passing that the Dockerfile's build stage is `golang:1.12.1`, older than the module's `go 1.18` directive, which is a separate problem it reports rather than fixes.

The change keeps `main.go` small. The agent moves the wiring into a `run(ctx context.Context, addr string) error` function: it creates the context with `signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)`, starts `r.Start(addr)` in a goroutine and sends its error on a channel, then selects on that channel and on `ctx.Done()`. On a signal it calls `r.Shutdown` with a `context.WithTimeout` of ten seconds, which is Echo's wrapper around `http.Server.Shutdown`: the listener closes, idle connections close, and active handlers get until the deadline to return. After `Shutdown` returns it calls `d.Close()` on the GORM handle. An error from `Start` other than `http.ErrServerClosed` is returned and logged, so a port already in use still exits non-zero as it does today.

A test proves the drain rather than asserting on log lines. `main_test.go` builds the router with `router.New()`, registers a handler that sleeps for a few hundred milliseconds, assigns `net.Listen("tcp", "127.0.0.1:0")` to `e.Listener` so the test owns the port, starts `run` with a cancellable context, fires the slow request, cancels the context while it is in flight, and asserts that the request still completes with 200 and that `run` returns `nil` before the timeout. The agent runs `gofmt -l`, `go vet ./...`, `go build -race .` and `go test -v -race ./...` as `Makefile` does, which also exercises the 25 existing handler tests against their SQLite fixture database.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add graceful shutdown to this Echo application. Read go.mod, main.go, router/router.go, handler/routes.go, db/db.go, Makefile, Dockerfile and .github/workflows/go.yml first. Move the server start in main.go into a run(ctx, addr) function that listens for SIGINT and SIGTERM with signal.NotifyContext, starts the Echo server in a goroutine, and on a signal calls Shutdown with a ten-second timeout and then closes the GORM database handle; treat http.ErrServerClosed as a clean exit and return any other Start error. Write main_test.go that starts run on a 127.0.0.1:0 listener, sends a request to a deliberately slow handler, cancels the context mid-request, and asserts the request completes with 200 and run returns before the timeout. Run gofmt -l, go vet ./..., go build -race . and go test -v -race ./..., and open a pull request that explains the shutdown order and notes anything in the Dockerfile that affects signal delivery.",
  "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 that changes `main.go` and adds `main_test.go`. The description states the order of operations on a signal: stop accepting, drain active requests for at most ten seconds, close the database, exit zero. It names `http.ErrServerClosed` as the expected result of `Start` after `Shutdown`, and it points out that the Dockerfile runs the binary as PID 1, so no init wrapper is needed for the signal to arrive.

The run's record keeps the `go vet`, build and test output, including the new shutdown test alongside the existing handler suite, so a reviewer can see the drain test pass under `-race` rather than take the description's word for it.

Before merging, a reviewer decides whether ten seconds matches the platform's grace period (Kubernetes defaults to thirty before `SIGKILL`, and a load balancer's drain time may be shorter), and whether the hard-coded `127.0.0.1:8585` should become a flag or environment variable while this code is being touched; the agent leaves the address alone and says so.

## Run it on every Go service repository

A team with several Echo services runs this once per repository from its own server: one `POST /o/{org}/sessions` per repository, each with that repository in `resources` and a `request_id` that is a UUID v5 of the repository's full name, so a retried call returns the run already started instead of opening a second pull request. Each run clones its repository into its own sandbox and the pull requests arrive independently.

To keep it from regressing, an automation on the Project with a `github` trigger on `pull_request.opened` and the prompt "check that main.go still stops the server through run() and Shutdown; comment on the pull request if a change bypasses it" reads each new pull request. The trigger puts the pull request after the prompt; only work by an owner, member or collaborator fires it, never a fork's.

## Why run it on Rush?

Shutdown code is the kind that looks right and is never exercised: the only way to know a drain works is to send the signal while a request is in flight and watch what the client gets. The agent does that in its own sandbox, with a real listener on a free port and the race detector on, and the test stays in the repository so the next change to `main.go` is checked the same way.

Every command the agent ran stays with the run, from `go vet` to the test output, so the pull request can cite the passing drain test and the unchanged handler suite. Running several services this way at once costs no more attention than one, because each run has its own machine and its own record.

## Frequently asked questions

### Does Echo not handle SIGTERM on its own?

No. `e.Start` blocks until the listener returns an error, and Echo installs no signal handler. Without one, the Go runtime's default action on `SIGTERM` is to terminate the process immediately, which is what happens today. Echo provides `Shutdown` and `Close`; wiring a signal to `Shutdown` is the application's job.

### Why close the database after Shutdown and not before?

Handlers still running during the drain use the GORM handle. Closing it first would turn their last queries into errors, which defeats the point of draining. `Shutdown` returns once active requests have finished or the deadline passed, and only then is it safe to call `Close`.

### Will this change the Dockerfile?

No. The runtime image runs the binary as PID 1 with no shell in front of it, so `docker stop` and a Kubernetes pod deletion deliver `SIGTERM` directly. The agent does note that the build stage pins `golang:1.12.1` while `go.mod` says `go 1.18`, which is unrelated and left for a separate change.

### What about the test database the handler tests use?

Untouched. `db.TestDB()` opens `./../realworld_test.db` and `TestMain` in `handler/handler_test.go` drops it at the end. The new `main_test.go` lives in package `main`, opens no database, and uses a handler that only sleeps, so the two suites do not interfere.

## More Echo jobs

- [Add Health Checks to an Echo API](https://getrush.ai/run/add-health-checks/echo/)
- [Run an Echo App as a Non-Root User in Docker](https://getrush.ai/run/add-non-root-user/echo/)
- [Add OpenTelemetry Tracing to an Echo API](https://getrush.ai/run/add-opentelemetry/echo/)

## The same job on other stacks

- [Add Graceful Shutdown to a Fiber App](https://getrush.ai/run/add-graceful-shutdown/fiber/)
- [Add Graceful Shutdown to a Gin API](https://getrush.ai/run/add-graceful-shutdown/gin/)
- [Add Graceful Shutdown to a Go Service from a Linear Issue](https://getrush.ai/run/add-graceful-shutdown/go/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
