Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 0 additions & 6 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -86,11 +86,5 @@ jobs:
name: vendor-artifact
path: .

- name: Clean up Docker
run: docker system prune -f

- name: Create Docker volume for migrations
run: docker volume create test-adm-migrations

- name: Run tests
run: make tests
9 changes: 3 additions & 6 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -14,11 +14,10 @@ PHP_VERSION := $(shell sed -n 's/.*"php": *"^\([0-9]*\.[0-9]*\)".*/\1/p' compose
PHP_IMAGE := gustavofreze/php:${PHP_VERSION}-cli
WORKSPACE := /var/www/html

DOCKER_RUN = docker run ${PLATFORM} -u ${HOST_USER} --rm ${TTY} --network=tiny-blocks --name test-lib \
DOCKER_RUN = docker run ${PLATFORM} -u ${HOST_USER} --rm ${TTY} --network=tiny-blocks \
$(if $(DOCKER_GID),--group-add $(DOCKER_GID)) \
-e COMPOSER_HOME=/tmp/composer \
-v ${PWD}:${WORKSPACE} \
-v ${PWD}/tests/Integration/Database/Migrations:/test-adm-migrations \
-v /var/run/docker.sock:/var/run/docker.sock \
${PHP_IMAGE}

Expand All @@ -41,14 +40,12 @@ tests: configure-test-environment ## Run unit and mutation tests with coverage
@${DOCKER_RUN} composer tests

.PHONY: test-file
test-file: ## Run tests for a specific file (usage: make test-file FILE=ClassNameTest)
test-file: configure-test-environment ## Run tests for a specific file (usage: make test-file FILE=ClassNameTest)
@${DOCKER_RUN} composer test-file ${FILE}

.PHONY: configure-test-environment
configure-test-environment:
@if ! docker network inspect tiny-blocks > /dev/null 2>&1; then \
docker network create --label tiny-blocks.docker-container=true tiny-blocks > /dev/null 2>&1; \
fi
@docker network create tiny-blocks > /dev/null 2>&1 || true

.PHONY: review
review: configure-test-environment ## Run lint and static analysis
Expand Down
51 changes: 42 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@
+ [Setting tmpfs mounts](#setting-tmpfs-mounts)
+ [Setting environment variables](#setting-environment-variables)
+ [Disabling auto-remove](#disabling-auto-remove)
+ [Setting the image pull timeout](#setting-the-image-pull-timeout)
+ [Copying files to a container](#copying-files-to-a-container)
+ [Stopping a container](#stopping-a-container)
+ [Stopping on shutdown](#stopping-on-shutdown)
Expand Down Expand Up @@ -101,6 +102,9 @@ $container->run(commands: ['ls', '-la']);
To wait after the container starts, register a wait strategy on the definition (see
[Wait strategies](#wait-strategies)).

A container that fails to receive its files, to start, or to satisfy a wait strategy is removed before the failure is
raised, since nothing else holds it.

### Running if not exists

Starts a container only if a container with the same name does not exist yet, and reuses it otherwise. The returned
Expand All @@ -109,6 +113,10 @@ neither `stopOnShutdown()` nor `remove()`: no single process owns it. When the c
container removes the shared container once the test runner container exits. The wait strategies registered with
`withWaitAfterStarted()` apply only when a new container starts.

Processes that ask for the same name at the same time are safe: Docker lets only one of them create the container,
and the others reuse it. A container another process has created but not started yet is handed over only once it
has started, so its address already carries the ports Docker assigned.

```php
$container->runIfNotExists();
```
Expand Down Expand Up @@ -136,6 +144,9 @@ $execution->getOutput(); # "done\n"
A non-zero exit raises `ContainerExitUnsuccessful` carrying what the container wrote to its standard error. A
container still running when the timeout elapses raises `ContainerWaitTimeout`.

The removal runs in the PHP process that started the container. If that process is killed while the container runs,
the container is left behind.

### Checking if the container was reused

Tells whether the shared container came from an already-running instance. This distinguishes a fresh start from a
Expand All @@ -152,7 +163,8 @@ $alreadyRunning = $started->wasReused();

Sets the Docker network the container should join. The network is created automatically when the container runs, if
it does not already exist. Networks created by the library are labeled with `tiny-blocks.docker-container=true` for
safe cleanup.
safe cleanup. When a cleanup running in parallel removes the network before the container starts, the network is
created again and the container is started once more.

```php
$container = $container->withNetwork(name: 'my-network');
Expand Down Expand Up @@ -209,10 +221,26 @@ By default, containers are removed when stopped. This disables that behavior.
$container = $container->withoutAutoRemove();
```

### Setting the image pull timeout

Bounds how long creating the container may take, which includes pulling the image when it is not available locally.
The default is 300 seconds. Raise it for large images on slow connections.

```php
<?php

declare(strict_types=1);

use TinyBlocks\Time\Duration;

$container = $container->withPullTimeout(timeout: Duration::fromSeconds(seconds: 600));
```

### Copying files to a container

Registers files or directories to be copied from the host into the container. The files are copied after the
container is created and before it starts, so its command already sees them.
container is created and before it starts, so its command already sees them. A copy that fails raises
`DockerCommandExecutionFailed` and removes the container that was created, so it never starts without its files.

```php
$container = $container->copyToContainer(pathOnHost: '/path/to/files', pathOnContainer: '/path/in/container');
Expand Down Expand Up @@ -293,8 +321,9 @@ $container = $container

#### Waiting for a dependency

Polls a readiness condition every 250 milliseconds until it holds, and raises `ContainerWaitTimeout` once the timeout
(30 seconds by default) elapses. This is useful when one container depends on another being fully ready.
Checks a readiness condition until it holds, pausing 250 milliseconds after each check that fails, and raises
`ContainerWaitTimeout` once the timeout (30 seconds by default) elapses. The time each check takes counts toward the
timeout. This is useful when one container depends on another being fully ready.

```php
<?php
Expand Down Expand Up @@ -323,8 +352,10 @@ $container = GenericDockerContainer::from(image: 'my-app:latest')

`MySQLDockerContainer` provides a specialized container for MySQL databases. Both `run()` and `runIfNotExists()`
hand the container over only once MySQL accepts connections, and create the database and the root grants when they
are configured. Both return a `MySQLContainerStarted`: the one from `run()` is also a `DisposableContainer`, and the
one from `runIfNotExists()` is also a `SharedContainer`.
are configured. A setup MySQL rejects raises `DockerCommandExecutionFailed` carrying the MySQL error. A container
from `run()` that never accepts connections, or whose setup fails, is removed before the failure is raised. Both
return a `MySQLContainerStarted`: the one from `run()` is also a `DisposableContainer`, and the one from
`runIfNotExists()` is also a `SharedContainer`.

#### Configuring MySQL options

Expand All @@ -336,6 +367,7 @@ one from `runIfNotExists()` is also a `SharedContainer`.
| `withDatabase` | `$database` | Sets the default database created on startup. |
| `withRootPassword` | `$rootPassword` | Sets the root password for the MySQL instance. |
| `withGrantedHosts` | `$hosts` | Sets hosts granted root privileges (default: `['%', '172.%']`). |
| `withPullTimeout` | `$timeout` | Sets how long creating the container, pull included, may take. |

```php
<?php
Expand All @@ -359,7 +391,7 @@ $mySQLStarted = MySQLDockerContainer::from(image: 'mysql:8.4')
#### Setting readiness timeout

Configures how long `run()` and `runIfNotExists()` wait for MySQL to accept connections before throwing a
`ContainerWaitTimeout` exception. The default timeout is 30 seconds.
`ContainerWaitTimeout` exception. The default timeout is 60 seconds.

```php
<?php
Expand Down Expand Up @@ -522,6 +554,7 @@ $flyway = $flyway->withMigrations(pathOnHost: '/path/to/migrations');
| `withTable` | `$table` | Overrides the history table name (default: `schema_history`). |
| `withSchema` | `$schema` | Overrides the target schema (default: detected from MySQL). |
| `withTimeout` | `$timeout` | Sets how long each command waits for Flyway to exit (120 s). |
| `withPullTimeout` | `$timeout` | Sets how long creating the container, pull included, may take. |
| `withCredentials` | `$password`, `$username` | Overrides the credentials (default: root, from MySQL). |
| `withConnectRetries` | `$retries` | Sets the number of database connection retries. |
| `withMigrationNamingValidation` | | Rejects migrations whose file names break the naming convention. |
Expand Down Expand Up @@ -597,8 +630,8 @@ Every factory accepts a `DockerClient`, the single boundary through which the li
defaults to the local `docker` executable. A custom client can route the commands to another Docker-compatible engine,
or stand in for the engine in the unit tests of code that builds containers. A `DockerCommand` carries only its
arguments and runs through `execute()`, within the default timeout of the client. A `DockerCommandWithTimeout`, such as
a container run to completion or a stop, also carries the timeout it must finish within and runs through
`executeWithTimeout()`:
a container creation, a container run to completion, or a stop, also carries the timeout it must finish within and runs
through `executeWithTimeout()`:

```php
<?php
Expand Down
6 changes: 5 additions & 1 deletion composer.json
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,11 @@
"psr-4": {
"Test\\": "tests/",
"TinyBlocks\\DockerContainer\\": "tests/Unit/"
}
},
"files": [
"tests/Unit/Internal/Containers/Overrides/host.php",
"tests/Unit/Waits/Overrides/clock.php"
]
},
"config": {
"allow-plugins": {
Expand Down
32 changes: 11 additions & 21 deletions phpstan.neon.dist
Original file line number Diff line number Diff line change
Expand Up @@ -8,15 +8,15 @@ parameters:
# tiny-blocks/collection generics carry a mixed TValue on Internal command and definition types.
- identifier: missingType.generics
paths:
- src/Internal/Commands/DockerExecute.php
- src/Internal/Commands/DockerCreate.php
- src/Internal/Containers/ContainerWaits.php
- src/Internal/Containers/Definitions/ContainerDefinition.php
- src/Internal/Containers/Environment/EnvironmentVariables.php
# Internal collaborators take raw config arrays at the boundary, where PHPDoc is prohibited.
- identifier: missingType.iterableValue
paths:
- src/Internal/Containers/ContainerLauncher.php
- src/Internal/Containers/ContainerSharing.php
- src/Internal/Containers/ContainerStartup.php
- src/Internal/Containers/SharedStart.php
- src/Internal/Containers/OneShotContainer.php
- src/Internal/Containers/Drivers/MySQL/MySQLStartup.php
- src/Internal/Commands/DockerExecute.php
Expand All @@ -27,6 +27,7 @@ parameters:
- src/Internal/Containers/Definitions/CopyInstruction.php
- src/Internal/Containers/Drivers/MySQL/JdbcUrl.php
- src/Internal/Containers/Drivers/Flyway/FlywaySettings.php
- src/Internal/Containers/Drivers/Flyway/FlywaySource.php
- src/Internal/Containers/Drivers/MySQL/MySQLCommands.php
- src/Internal/Containers/Environment/EnvironmentVariables.php
# Internal command builders return argument lists assembled from collection mixed values.
Expand All @@ -43,9 +44,6 @@ parameters:
- src/Internal/Containers/ContainerWaits.php
- src/Internal/Containers/Address/Ports.php
- src/Internal/Containers/Definitions/ContainerDefinition.php
# ContainerSharing starts a new container through a plain Closure, whose result is mixed to phpstan.
- identifier: argument.type
path: src/Internal/Containers/ContainerSharing.php
# docker inspect json_decode and sprintf feed mixed values across the system boundary.
- identifier: argument.type
paths:
Expand All @@ -72,12 +70,16 @@ parameters:
# Environment variable values arrive as mixed and are cast to string at the boundary.
- identifier: cast.string
path: src/Internal/Containers/Environment/EnvironmentVariables.php
# docker inspect json_decode yields a mixed container ID cast to string at the boundary.
- identifier: cast.string
path: src/Internal/Containers/ContainerInspection.php
# Fixtures and mocks accept raw arrays, where PHPDoc is prohibited inside tests.
- identifier: missingType.iterableValue
paths:
- tests/Integration/MySQLRepository.php
- tests/Models/InspectResponseFixture.php
- tests/Unit/ClientMock.php
- tests/Unit/HostMock.php
# ClientMock and fixtures hand mixed values to typed sinks and assertions in tests.
- identifier: argument.type
paths:
Expand All @@ -97,23 +99,11 @@ parameters:
path: tests/Unit/ClientMock.php
# Tests index into the untyped argument lists the ClientMock records.
- identifier: offsetAccess.nonOffsetAccessible
paths:
- tests/Unit/FlywayDockerContainerTest.php
- tests/Unit/GenericDockerContainerTest.php
# The shutdown spy records callbacks in an untyped global the test then invokes.
path: tests/Unit/FlywayDockerContainerTest.php
# HostMock records shutdown callbacks in an untyped list it then invokes.
- identifier: callable.nonCallable
path: tests/Unit/GenericDockerContainerTest.php
# Immutability tests discard the copy a with* method returns, to show the receiver is untouched.
- identifier: method.resultUnused
paths:
- tests/Unit/FlywayDockerContainerTest.php
- tests/Unit/MySQLDockerContainerTest.php
path: tests/Unit/HostMock.php
# MySQLRepository reads a mixed PDO result as an object at the system boundary.
- identifier: method.nonObject
path: tests/Integration/MySQLRepository.php
# Mock-verified and no-exception tests assert a literal true to satisfy the assertion count.
- identifier: staticMethod.alreadyNarrowedType
paths:
- tests/Unit/GenericDockerContainerTest.php
- tests/Unit/Waits/ContainerWaitForDependencyTest.php
reportUnmatchedIgnoredErrors: true
43 changes: 22 additions & 21 deletions src/FlywayDockerContainer.php
Original file line number Diff line number Diff line change
Expand Up @@ -133,11 +133,7 @@ public function withSchema(string $schema): FlywayDockerContainer
*/
public function withSource(MySQLDockerContainer $container): FlywayDockerContainer
{
return new FlywayDockerContainer(
timeout: $this->timeout,
settings: $this->settings->withSource(source: $container),
container: $this->container
);
return clone($this, ['settings' => $this->settings->withSource(source: $container)]);
}

/**
Expand All @@ -148,11 +144,7 @@ public function withSource(MySQLDockerContainer $container): FlywayDockerContain
*/
public function withNetwork(string $name): FlywayDockerContainer
{
return new FlywayDockerContainer(
timeout: $this->timeout,
settings: $this->settings,
container: $this->container->withNetwork(name: $name)
);
return clone($this, ['container' => $this->container->withNetwork(name: $name)]);
}

/**
Expand All @@ -165,7 +157,7 @@ public function withNetwork(string $name): FlywayDockerContainer
*/
public function withTimeout(Duration $timeout): FlywayDockerContainer
{
return new FlywayDockerContainer(timeout: $timeout, settings: $this->settings, container: $this->container);
return clone($this, ['timeout' => $timeout]);
}

/**
Expand All @@ -180,17 +172,16 @@ public function withMigrations(string $pathOnHost): FlywayDockerContainer
{
$template = 'filesystem:%s';

return new FlywayDockerContainer(
timeout: $this->timeout,
settings: $this->settings->with(
return clone($this, [
'settings' => $this->settings->with(
key: 'FLYWAY_LOCATIONS',
value: sprintf($template, self::MIGRATIONS_ON_CONTAINER)
),
container: $this->container->copyToContainer(
'container' => $this->container->copyToContainer(
pathOnHost: $pathOnHost,
pathOnContainer: self::MIGRATIONS_ON_CONTAINER
)
);
]);
}

/**
Expand Down Expand Up @@ -243,6 +234,20 @@ public function withCredentials(string $password, string $username): FlywayDocke
->withEnvironmentVariable(key: 'FLYWAY_PASSWORD', value: $password);
}

/**
* Returns a copy of the FlywayDockerContainer with the image pull timeout replaced.
*
* <p>The timeout bounds how long creating the container may take, which includes pulling the image when it
* is not available locally. It defaults to 300 seconds.</p>
*
* @param Duration $timeout The longest time creating the container, image pull included, may take.
* @return FlywayDockerContainer The copy with the new image pull timeout.
*/
public function withPullTimeout(Duration $timeout): FlywayDockerContainer
{
return clone($this, ['container' => $this->container->withPullTimeout(timeout: $timeout)]);
}

/**
* Returns a copy of the FlywayDockerContainer with the number of database connection retries replaced.
*
Expand All @@ -265,11 +270,7 @@ public function withConnectRetries(int $retries): FlywayDockerContainer
*/
public function withEnvironmentVariable(string $key, string $value): FlywayDockerContainer
{
return new FlywayDockerContainer(
timeout: $this->timeout,
settings: $this->settings->with(key: $key, value: $value),
container: $this->container
);
return clone($this, ['settings' => $this->settings->with(key: $key, value: $value)]);
}

/**
Expand Down
Loading