All jobs

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 RushOpens 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 with this body:

{
  "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.

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

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

The same job on other stacks

Keep reading