feat: include healthcheck status in Docker container inspect() result#1348
Open
aleclarson wants to merge 2 commits intoalchemy-run:mainfrom
Open
feat: include healthcheck status in Docker container inspect() result#1348aleclarson wants to merge 2 commits intoalchemy-run:mainfrom
inspect() result#1348aleclarson wants to merge 2 commits intoalchemy-run:mainfrom
Conversation
* feat: include healthcheck status in Docker container inspect() result Co-authored-by: aleclarson <1925840+aleclarson@users.noreply.github.com> * test(docker): use spyOn exec instead of mocking DockerApi module Refactor test to spy on DockerApi.prototype.exec instead of mocking the entire module, ensuring better coverage of internal logic while simulating CLI output. Co-authored-by: aleclarson <1925840+aleclarson@users.noreply.github.com> * test(docker): switch to real docker tests with safe failure mode Replace mocked tests with real Docker container tests using busybox, handling environment limitations like rate limits gracefully. Co-authored-by: aleclarson <1925840+aleclarson@users.noreply.github.com> * feat(docker): add waitForHealth method to Container resource Add waitForHealth method to Container resource to allow waiting for healthy status, and update tests to use it. Co-authored-by: aleclarson <1925840+aleclarson@users.noreply.github.com> * refactor(docker): hoist container methods to avoid duplication Hoist inspect and waitForHealth methods in Container resource implementation to avoid code duplication across execution branches. Co-authored-by: aleclarson <1925840+aleclarson@users.noreply.github.com> * feat(docker): update waitForHealth to return runtime info Update waitForHealth to return ContainerRuntimeInfo on success, providing immediate access to container details. Co-authored-by: aleclarson <1925840+aleclarson@users.noreply.github.com> * chore: prevent API drift * chore: revert name change * chore: revert tsconfig change --------- Co-authored-by: google-labs-jules[bot] <161369871+google-labs-jules[bot]@users.noreply.github.com>
commit: |
aleclarson
changed the title
inspect() result (#8)inspect() result
Mkassabov
reviewed
Mar 5, 2026
Comment on lines
+343
to
+372
| const waitForHealth: Container["waitForHealth"] = async ( | ||
| timeout = 60000, | ||
| ) => { | ||
| const startTime = Date.now(); | ||
| while (Date.now() - startTime < timeout) { | ||
| const [info] = await api.inspectContainer(containerName); | ||
| if (!info) { | ||
| throw new Error(`Container ${containerName} not found`); | ||
| } | ||
|
|
||
| const health = info.State.Health?.Status; | ||
| if (health === "healthy") { | ||
| return toRuntimeInfo(info); | ||
| } | ||
| if (health === "unhealthy") { | ||
| throw new Error(`Container ${containerName} is unhealthy`); | ||
| } | ||
| if (!health || health === "none") { | ||
| throw new Error( | ||
| `Container ${containerName} has no healthcheck configured`, | ||
| ); | ||
| } | ||
|
|
||
| // Wait 500ms before next check | ||
| await new Promise((resolve) => setTimeout(resolve, 500)); | ||
| } | ||
| throw new Error( | ||
| `Timed out waiting for container ${containerName} to become healthy`, | ||
| ); | ||
| }; |
Collaborator
There was a problem hiding this comment.
I'm not sure if waitForHealth makes sense as an alchemy feature.
- a service can be unhealthy and then transition to healthy (which might not make sense here) so throwing an error on unhealthy seems a little bit unexpected.
- I think wait for checks often have enough logic tied into them that a generic solution might not be great (e.g. timeout being 500)
- this almost makes more sense as part of the resources creation lifecycle rather than a method on it.
Could you briefly explain why you want this as part of alchemy?
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.
Feel free to edit this one as you see fit!
Summary
This PR introduces support for monitoring and waiting on Docker container health checks. It updates the internal Docker API types to expose health status and adds a new method to the
Containerresource to synchronize actions based on a container's health state.Key Changes
ContainerStateto include theHealthobject, which tracks status (starting,healthy,unhealthy), failure counts, and log output.waitForHealth(): Added a method to theContainerclass that polls the container's state until it reports ashealthy.unhealthy.container.test.tsto verify the inspection logic andwaitForHealthbehavior across various states (healthy, unhealthy, starting, and unconfigured).Impact
This allows users to ensure a service inside a container is fully operational and passed its internal health checks before proceeding with dependent tasks, rather than relying solely on the container's "running" status.