Skip to content

Add structured logging and graceful shutdown #35

Closed

Description

@lmcorbalan

User story / Problem statement

As an operator, I want to know when the service fails and I want it to start and stop cleanly, so that a ledger outage is visible in my logs rather than silent, and a deploy does not sever in-flight requests. Currently the terminal error handler returns a clean 500 but logs nothing at all, and the process has no signal handling.

Expected outcome

Every 5xx is logged with structure. A configuration error exits non-zero with a readable message instead of dumping a raw stack. On SIGTERM or SIGINT the service stops accepting connections, lets in-flight requests finish, and force-closes anything still open at a configurable deadline.

Acceptance criteria

  • A structured logger is used, injected through the server dependencies so tests can capture output
  • The terminal error handler logs every 5xx
  • A configuration error logs and exits non-zero
  • SIGTERM and SIGINT share one shutdown path, guarded against re-entry
  • In-flight requests are allowed to drain, with a configurable timeout backstop
  • The timeout is documented with guidance for container stop grace periods
  • The suite is green and produces no stray log output

Alternatives considered

A shutdown library was considered and declined in favor of a hand-rolled drain, which is a small amount of code and avoids a dependency for something this specific.

The naive server.close(callback) pattern was rejected: it hangs indefinitely while keep-alive connections remain open, so idle connections must be released first and a timer backstop must force-close the rest.

Technical notes

The backstop timer must be unref'd so it never keeps the process alive on its own.

Additional context

Part of #22. Implemented by #16.

Activity

  1. lmcorbalan commented on Jul 22, 2026

    @lmcorbalan
    CollaboratorAuthor

    Delivered by #16, merged 2026-07-21, before issue tracking was set up on this repo. Recorded here for traceability.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestpriority: highMust be addressed in current sprint

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions