chore(docs): add a graceful shutdown section to the README - #159
Draft
schematic-orbit wants to merge 1 commit into
Draft
chore(docs): add a graceful shutdown section to the README#159schematic-orbit wants to merge 1 commit into
schematic-orbit wants to merge 1 commit into
Conversation
close() is awaitable and flushes the event buffer, but the README never said so and showed it unawaited everywhere. Adds a Graceful shutdown H2 with a SIGTERM/SIGINT handler, spells out the flush semantics (3 retries with exponential backoff), calls out that dropped track events carrying a leaseId leave work unbilled, and documents the in-memory vs shared Redis lease-release difference. Also awaits close() in the Cloudflare Worker example, whose handler is already async.
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
1 participant
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.
Documents graceful shutdown, prompted by a customer (#schematic-syrto) who hit
the real failure mode: a credit-lease redemption
trackis bufferedclient-side, and if the process takes a SIGTERM before it flushes, the lease's
unspent remainder is refunded at release/expiry and the work goes unbilled.
close()already awaits the buffer flush (3 retries, exponential backoff), sothe fix on their side is one line — but the README never said so and showed
client.close()unawaited in all 17 snippets.## Graceful shutdownH2 after Installation and Setup: SIGTERM/SIGINThandler, the flush semantics, the lease-redemption consequence of dropping
events, and the in-memory vs shared-Redis lease-release difference already
documented on
close()insrc/wrapper.ts.close()in the Cloudflare Worker example, whose handler is alreadyasync. The other 16 calls are left alone — they sit at the top level ofstandalone snippets, so a blanket
awaitwould be wrong; the new sectionsays as much explicitly.
nodejs.mdxinschematic-fern-configis generated from this README byscripts/sync_sdk_readmes.py, so it picks this up on the next weekly sync(Mon 11:00 UTC) or via
workflow_dispatch— no fern-config edit needed.Verified: all 30 ```ts blocks parse cleanly under the TypeScript parser, no
awaitintroduced outside an async context (checked by AST walk, not grep),code fences balanced, all in-page anchors resolve. Not verified: docs-site
rendering of the regenerated `nodejs.mdx` — that only exists after the sync runs.
Companion: SchematicHQ/schematic-fern-config#413 fixes the sync script so the
generated
nodejs.mdxkeeps its site-relative docs links instead of having themclobbered on the next sync. Independent of this PR; either can land first.