Notify replaced plugin processes at upgrade grace start

Send rpc.superseded with the newly active hash before activation returns.
Add an opt-in SDK hook and drain helper that closes SDK listeners and idle
connections without cancelling active handlers or background work.
Document the additive notice and preserve existing grace, stop and restart rules.

Cover immediate notices, ignored notices, early service restarts, SDK draining
and duplicate-hook diagnostics.

Card: SAU-352
This commit is contained in:
SAU-352 implementer
2026-10-29 18:50:10 +00:00
committed by surma
parent c54edea596
commit c04baee67c
12 changed files with 314 additions and 21 deletions
+9 -4
View File
@@ -70,7 +70,7 @@ Rust plugins use the SDK `sausage-plugin`. Its source is at
`notes.rpc.discover` sends it `rpc.discover`.
- `core.<method>` is a method of the core (section 9).
- Method names that start with `rpc.` are reserved: `rpc.discover`,
`rpc.retired`, and `rpc.endpoint`.
`rpc.superseded`, `rpc.retired`, and `rpc.endpoint`.
### 3.3 What a call does
@@ -153,9 +153,14 @@ A process is an instance of one plugin version. When a new version becomes
active (section 10.3):
1. New calls get the new version at once.
2. Each process of an older version gets a grace period to finish its work.
The default is 60 seconds. A plugin can declare its own value in
`rpc.discover` (`x-sausage-grace`). Then the core stops the process.
2. At grace start, the core sends each process of an older version the
JSON-RPC notification `rpc.superseded {"current": "<sha256 of the new file>"}`
on stdin, without an ID. The process is still running: calls and responses
continue to work. It can stop accepting work, finish its in-flight calls,
and exit early. Ignoring the notice changes nothing. The grace period is
the upper bound before the core stops the process (section 3.6); its
default is 60 seconds. A plugin can declare its own value in its old
`rpc.discover` document (`x-sausage-grace`).
3. When the old process of a service has ended, the core starts the service
again with the new version.
4. When the last process of an older version has ended, the core starts a