From b7103e9c552f0b9b2b661836df420579afb543db Mon Sep 17 00:00:00 2001 From: Kris Zyp Date: Wed, 26 Aug 2026 06:13:58 -0600 Subject: [PATCH 1/6] docs(operations): document that deploy_component waits for restart: true and reports restart_completed --- reference/operations-api/operations.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/reference/operations-api/operations.md b/reference/operations-api/operations.md index aea164d8..e192b170 100644 --- a/reference/operations-api/operations.md +++ b/reference/operations-api/operations.md @@ -887,6 +887,14 @@ Response: } ``` +#### Restarting (`restart`) + +`"restart": true` restarts this node's HTTP worker threads and waits for that restart to finish before responding, so a successful response means every worker thread is serving the newly deployed code. Until a worker has been replaced it is still running the previous code, and on platforms where replacements share a listening port it keeps accepting connections for the whole rolling restart — a client that treated the earlier immediate response as "the component is live" could be served by a worker that had never loaded it. + +The response carries `restart_completed` : `true` when no worker thread was left running the previous code, and `false` when the wait ran out (the restart continues in the background), when a worker could not be replaced, or when the restart was handed off to another thread and could not be awaited. The Harper log records which of those happened. A restart that fails does not fail the deploy — the component is already installed and replicated. + +`"restart": "rolling"` is unchanged: instead of restarting inline it starts a replicated `restart_service` job and returns its `restartJobId` to poll. + ### Deployment Operations Harper records every `deploy_component` call in the `system.hdb_deployment` table, capturing the full lifecycle of a deployment including phase transitions (prepare → load → replicate → restart → success/failed), per-node outcomes, and a bounded event log of install output. From dc084210c09e5da379ad8a5b1c659da63f424f60 Mon Sep 17 00:00:00 2001 From: Kris Zyp Date: Wed, 26 Aug 2026 06:23:23 -0600 Subject: [PATCH 2/6] docs(operations): move the restart version badge to standalone placement --- reference/operations-api/operations.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/reference/operations-api/operations.md b/reference/operations-api/operations.md index e192b170..8bbd31b7 100644 --- a/reference/operations-api/operations.md +++ b/reference/operations-api/operations.md @@ -889,9 +889,11 @@ Response: #### Restarting (`restart`) -`"restart": true` restarts this node's HTTP worker threads and waits for that restart to finish before responding, so a successful response means every worker thread is serving the newly deployed code. Until a worker has been replaced it is still running the previous code, and on platforms where replacements share a listening port it keeps accepting connections for the whole rolling restart — a client that treated the earlier immediate response as "the component is live" could be served by a worker that had never loaded it. + -The response carries `restart_completed` : `true` when no worker thread was left running the previous code, and `false` when the wait ran out (the restart continues in the background), when a worker could not be replaced, or when the restart was handed off to another thread and could not be awaited. The Harper log records which of those happened. A restart that fails does not fail the deploy — the component is already installed and replicated. +`"restart": true` restarts this node's HTTP worker threads and now waits for that restart to finish before responding, so a successful response means every worker thread is serving the newly deployed code. Until a worker has been replaced it is still running the previous code, and on platforms where replacements share a listening port it keeps accepting connections for the whole rolling restart — a client that treated the earlier immediate response as "the component is live" could be served by a worker that had never loaded it. + +The response carries `restart_completed` (v5.2.7): `true` when no worker thread was left running the previous code, and `false` when the wait ran out (the restart continues in the background), when a worker could not be replaced, or when the restart was handed off to another thread and could not be awaited. The Harper log records which of those happened. A restart that fails does not fail the deploy — the component is already installed and replicated. `"restart": "rolling"` is unchanged: instead of restarting inline it starts a replicated `restart_service` job and returns its `restartJobId` to poll. From 857557069bb1fbb389db1ba926793792ca4cee30 Mon Sep 17 00:00:00 2001 From: Kris Zyp Date: Wed, 26 Aug 2026 06:52:41 -0600 Subject: [PATCH 3/6] docs(operations): describe the progress-gated wait, the omitted field, and drop_component --- reference/operations-api/operations.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/reference/operations-api/operations.md b/reference/operations-api/operations.md index 8bbd31b7..e838d6c4 100644 --- a/reference/operations-api/operations.md +++ b/reference/operations-api/operations.md @@ -893,10 +893,14 @@ Response: `"restart": true` restarts this node's HTTP worker threads and now waits for that restart to finish before responding, so a successful response means every worker thread is serving the newly deployed code. Until a worker has been replaced it is still running the previous code, and on platforms where replacements share a listening port it keeps accepting connections for the whole rolling restart — a client that treated the earlier immediate response as "the component is live" could be served by a worker that had never loaded it. -The response carries `restart_completed` (v5.2.7): `true` when no worker thread was left running the previous code, and `false` when the wait ran out (the restart continues in the background), when a worker could not be replaced, or when the restart was handed off to another thread and could not be awaited. The Harper log records which of those happened. A restart that fails does not fail the deploy — the component is already installed and replicated. +The response carries `restart_completed` (v5.2.7): `true` when no worker thread was left running the previous code, and `false` when the wait gave up — the restart stopped reporting progress, hit the wait's absolute ceiling, or left a worker thread that could not be replaced. In each of those cases the restart continues in the background, and the Harper log records which one happened. The field is omitted when the responding thread did not perform the restart itself and therefore cannot report on it, which is the normal case for a peer applying a replicated deploy. A restart that fails does not fail the deploy — the component is already installed and replicated. + +The wait follows the restart's own progress rather than a fixed timeout, so a wide thread pool, a slow component install, or a worker draining in-flight work does not cut it short. `"restart": "rolling"` is unchanged: instead of restarting inline it starts a replicated `restart_service` job and returns its `restartJobId` to poll. +`drop_component` accepts `"restart": true` the same way, waits for the restart, and reports `restart_completed` on the same terms . + ### Deployment Operations Harper records every `deploy_component` call in the `system.hdb_deployment` table, capturing the full lifecycle of a deployment including phase transitions (prepare → load → replicate → restart → success/failed), per-node outcomes, and a bounded event log of install output. From ce02dcfcde0760babedd0fb2833a3a0fb3a940b0 Mon Sep 17 00:00:00 2001 From: Kris Zyp Date: Wed, 26 Aug 2026 06:52:52 -0600 Subject: [PATCH 4/6] docs(operations): keep the drop_component version note as plain text --- reference/operations-api/operations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/operations-api/operations.md b/reference/operations-api/operations.md index e838d6c4..bf56866a 100644 --- a/reference/operations-api/operations.md +++ b/reference/operations-api/operations.md @@ -899,7 +899,7 @@ The wait follows the restart's own progress rather than a fixed timeout, so a wi `"restart": "rolling"` is unchanged: instead of restarting inline it starts a replicated `restart_service` job and returns its `restartJobId` to poll. -`drop_component` accepts `"restart": true` the same way, waits for the restart, and reports `restart_completed` on the same terms . +`drop_component` accepts `"restart": true` the same way, waits for the restart, and reports `restart_completed` on the same terms (v5.2.7). ### Deployment Operations From bac7e95a745be88870d4a74b1bb349c12ff26031 Mon Sep 17 00:00:00 2001 From: Kris Zyp Date: Thu, 27 Aug 2026 09:03:16 -0600 Subject: [PATCH 5/6] docs(operations): badge the restart change as v5.3.0 and drop the removed response field --- reference/operations-api/operations.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/reference/operations-api/operations.md b/reference/operations-api/operations.md index bf56866a..1fb71b8e 100644 --- a/reference/operations-api/operations.md +++ b/reference/operations-api/operations.md @@ -889,17 +889,15 @@ Response: #### Restarting (`restart`) - + -`"restart": true` restarts this node's HTTP worker threads and now waits for that restart to finish before responding, so a successful response means every worker thread is serving the newly deployed code. Until a worker has been replaced it is still running the previous code, and on platforms where replacements share a listening port it keeps accepting connections for the whole rolling restart — a client that treated the earlier immediate response as "the component is live" could be served by a worker that had never loaded it. +`"restart": true` restarts this node's HTTP worker threads and waits for that restart to finish before responding, so a successful response means every worker thread is serving the newly deployed code. Until a worker has been replaced it is still running the previous code, and on platforms where replacements share a listening port it keeps accepting connections for the whole rolling restart — before this, a client that treated the immediate response as "the component is live" could be served by a worker that had never loaded it. -The response carries `restart_completed` (v5.2.7): `true` when no worker thread was left running the previous code, and `false` when the wait gave up — the restart stopped reporting progress, hit the wait's absolute ceiling, or left a worker thread that could not be replaced. In each of those cases the restart continues in the background, and the Harper log records which one happened. The field is omitted when the responding thread did not perform the restart itself and therefore cannot report on it, which is the normal case for a peer applying a replicated deploy. A restart that fails does not fail the deploy — the component is already installed and replicated. - -The wait follows the restart's own progress rather than a fixed timeout, so a wide thread pool, a slow component install, or a worker draining in-flight work does not cut it short. +The wait follows the restart's own progress rather than a fixed timeout, so a wide thread pool, a slow component install, or a worker draining in-flight work does not cut it short. If it does give up — the restart stopped reporting progress, ran past the wait's absolute ceiling, or left a worker thread that could not be replaced — the restart continues in the background and the Harper log says which of those happened. A restart that fails does not fail the deploy: the component is already installed and replicated. `"restart": "rolling"` is unchanged: instead of restarting inline it starts a replicated `restart_service` job and returns its `restartJobId` to poll. -`drop_component` accepts `"restart": true` the same way, waits for the restart, and reports `restart_completed` on the same terms (v5.2.7). +`drop_component` accepts `"restart": true` and waits for the restart the same way (v5.3.0). ### Deployment Operations From ac9391eb4d49c33301dd36874470aa72d12148ab Mon Sep 17 00:00:00 2001 From: Kris Zyp Date: Thu, 27 Aug 2026 09:36:00 -0600 Subject: [PATCH 6/6] docs(operations): say that an awaited restart makes the deploy response take install + restart time --- reference/operations-api/operations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/operations-api/operations.md b/reference/operations-api/operations.md index 1fb71b8e..0e7743a4 100644 --- a/reference/operations-api/operations.md +++ b/reference/operations-api/operations.md @@ -893,7 +893,7 @@ Response: `"restart": true` restarts this node's HTTP worker threads and waits for that restart to finish before responding, so a successful response means every worker thread is serving the newly deployed code. Until a worker has been replaced it is still running the previous code, and on platforms where replacements share a listening port it keeps accepting connections for the whole rolling restart — before this, a client that treated the immediate response as "the component is live" could be served by a worker that had never loaded it. -The wait follows the restart's own progress rather than a fixed timeout, so a wide thread pool, a slow component install, or a worker draining in-flight work does not cut it short. If it does give up — the restart stopped reporting progress, ran past the wait's absolute ceiling, or left a worker thread that could not be replaced — the restart continues in the background and the Harper log says which of those happened. A restart that fails does not fail the deploy: the component is already installed and replicated. +The wait follows the restart's own progress rather than a fixed timeout, so a wide thread pool, a slow component install, or a worker draining in-flight work does not cut it short. That also means the response can take as long as the install plus the restart — tens of seconds on a slow install with many worker threads — so a caller with a short request timeout should use `"restart": "rolling"` and poll its job instead. If it does give up — the restart stopped reporting progress, ran past the wait's absolute ceiling, or left a worker thread that could not be replaced — the restart continues in the background and the Harper log says which of those happened. A restart that fails does not fail the deploy: the component is already installed and replicated. `"restart": "rolling"` is unchanged: instead of restarting inline it starts a replicated `restart_service` job and returns its `restartJobId` to poll.