(docs): Make stdio shutdown sequence platform-neutral#2466
Merged
Conversation
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
The stdio shutdown sequence referenced SIGTERM and SIGKILL, which are POSIX-only. Windows has no direct equivalent; TerminateProcess is a hard kill with no graceful intermediate step. Restructured the client steps to describe intent (close stdin, wait, force-kill) rather than POSIX mechanics, with a follow-up paragraph naming the platform-specific APIs and linking to their documentation. Added a normative SHOULD that servers exit on stdin EOF. This is the only portable graceful-shutdown signal, and honoring it reduces the need for forced termination. All four official SDKs already rely on stdin closure as the graceful phase on Windows. Applied to draft only. Fixes #1090 🏠 Remote-Dev: homespace
98f21a4 to
a7f693a
Compare
jonathanhefner
approved these changes
Mar 25, 2026
Contributor
Author
|
/lgtm force Given Jonathan's approval above. |
Contributor
There was a problem hiding this comment.
Approved on behalf of @localden via /lgtm force.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #1090.
Problem
The stdio shutdown sequence in
lifecycle.mdxprescribes closing stdin, then sendingSIGTERM, thenSIGKILL. These signals are POSIX-only. On Windows there is no clean equivalent:TerminateProcessis a hard kill (no handlers run), andGenerateConsoleCtrlEventhas enough caveats that libuv explicitly declined to implement it.A survey of the four official SDKs shows none of them attempt a graceful-signal intermediate step on Windows. They all close stdin, wait, then hard-kill via
TerminateProcessorTerminateJobObject. The spec's three-step escalation effectively collapses to two steps on Windows.Changes
Platform-neutral steps. Restructured the numbered list to describe intent (close stdin → wait → force-kill) rather than POSIX mechanics. Added a follow-up paragraph naming the platform-specific APIs with links to their documentation: POSIX
signal.h(Open Group), Win32TerminateProcessand Job Objects (Microsoft Learn).Server-side EOF obligation. Added a normative
SHOULDthat servers exit promptly when stdin closes or returns EOF. Per Larry Osterman's comment, this is the real fix: if servers honor stdin closure, forced termination becomes a rare fallback rather than the norm. Stdin close is the only portable graceful-shutdown signal.Scope
Draft spec only.