Skip to content

Make container startup safe under concurrency and surface the failures Docker reports. - #36

Merged
gustavofreze merged 4 commits into
mainfrom
feat/concurrency-safe-startup
Nov 13, 2026
Merged

gustavofreze merged 4 commits into
mainfrom
feat/concurrency-safe-startup

Conversation

@gustavofreze

Copy link
Copy Markdown
Member

Please follow the contributing guidelines.

Summary

runIfNotExists() is documented as shared by every PHP process that asks for the same name, yet six processes asking at the same time ended with one container and five DockerCommandExecutionFailed, because looking the container up and creating it were two separate steps. Several failures were also swallowed: a docker cp that failed left the container running without its files, and a database setup MySQL rejected was ignored, so the root grants were silently missing.

What changes

  1. Processes racing on the same name are safe. Docker lets one of them create the container, and the others reuse it once the creation conflicts. A container another process created but has not started yet is handed over only once it has started, so its address carries the ports Docker assigned. Measured with six parallel processes: one success and five failures before, six successes with the same container ID after.
  2. A file copy that fails raises DockerCommandExecutionFailed and removes the container that was created.
  3. A database setup MySQL rejects raises DockerCommandExecutionFailed carrying the MySQL error. The database name is quoted as an identifier, so a name such as my-db no longer breaks the setup and drops the grants with it.
  4. A container from run() that fails to start, to satisfy a wait strategy, or (MySQL) to accept connections is removed before the failure is raised, since nothing else holds it.
  5. A container that joins a network is created and started once more when the network was pruned before it started. On a host, with seven loops creating and removing containers on one network, 5 of 48 launches failed before and 0 of 175 after.
  6. withPullTimeout() bounds the container creation, which includes the image pull, instead of the 60 seconds of the default client timeout. It defaults to 300 seconds.
  7. ContainerWaitForDependency honors its timeout. The time each check takes now counts toward it: a 2 second timeout with a 250 millisecond check took 4 seconds before and takes 2 seconds after. Since the MySQL readiness wait was effectively longer than its 30 seconds, its default is now 60 seconds.
  8. The existing container is looked up with a single docker inspect --type container <name> instead of docker ps followed by docker inspect.

Internally, the definitions copy themselves with clone, the startup steps are split into collaborators without private methods, and the unit tests freeze the clock and the host environment instead of sleeping and spawning processes. The unit suite went from 27 to 3 seconds and the mutation run from 8 minutes 34 seconds to under 3 minutes on the same machine, with every mutant still killed.

The tooling network no longer carries the label the library prunes by, make test-file creates the network, and the fixed container name is gone, so two targets can run side by side.

Public API

The change is breaking, so the release is 6.0.0.

Changed: a failed file copy and a rejected MySQL setup now raise DockerCommandExecutionFailed instead of being ignored. The MySQL readiness timeout defaults to 60 seconds. A custom DockerClient receives the container creation and the reaper through executeWithTimeout(), and the lookup of an existing container as docker inspect --type container <name>.

Added: GenericDockerContainer::withPullTimeout(), MySQLDockerContainer::withPullTimeout() and FlywayDockerContainer::withPullTimeout().

Related issue

None.

Checklist

  • Tests added or updated.
  • Documentation updated when applicable.
  • make review passes.
  • make tests passes.

The tooling network carried the label the library prunes by, so a test
run of any project using the library removed it between two targets.
The fixed container name made two targets collide, test-file never
created the network, and the migrations mount had no consumer.
…ailures Docker reports.

- Reuse the container another process created first instead of failing on the name conflict, and hand it over only once it has started.
- Raise DockerCommandExecutionFailed when a file copy or the MySQL setup fails, and remove the container nobody holds.
- Start a container once more when its network was pruned before it started.
- Bound the container creation by withPullTimeout() instead of the default timeout of the client.
- Count the time each readiness check takes toward the timeout, and raise the MySQL default to 60 seconds.
- Quote the database name as an identifier in the MySQL setup.
- Replace the rebuilding withers with clone and split the internal steps into collaborators.
- Freeze the clock and the host environment in the unit tests instead of sleeping and spawning processes.
@gustavofreze
gustavofreze merged commit d29b099 into main Nov 13, 2026
5 checks passed
@gustavofreze
gustavofreze deleted the feat/concurrency-safe-startup branch November 13, 2026 23:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant