diff --git a/changelog.md b/changelog.md index c43bf92..b08ed59 100644 --- a/changelog.md +++ b/changelog.md @@ -1,5 +1,11 @@ # Changelog +## 2025-11-18 - 2.1.0 - feat(DockerHost) +Add DockerHost.ping() to check Docker daemon availability and document health-check usage + +- Add DockerHost.ping() method that issues a GET to /_ping and throws an error if the response status is not 200 +- Update README: show ping() in Quick Start, add health check examples (isDockerHealthy, waitForDocker) and mention Health Checks in Key Concepts + ## 2025-11-18 - 2.0.0 - BREAKING CHANGE(DockerHost) Rename DockerHost constructor option 'dockerSockPath' to 'socketPath' and update internal socket path handling diff --git a/readme.md b/readme.md index f7c2d10..a9074cc 100644 --- a/readme.md +++ b/readme.md @@ -38,11 +38,9 @@ import { DockerHost } from '@apiclient.xyz/docker'; const docker = new DockerHost({}); await docker.start(); -// Or connect to remote Docker host via TCP -const remoteDocker = new DockerHost({ - socketPath: 'tcp://192.168.1.100:2375', -}); -await remoteDocker.start(); +// Check if Docker is accessible +await docker.ping(); +console.log('✅ Docker is running'); // List all containers const containers = await docker.getContainers(); @@ -100,6 +98,48 @@ await docker.start(); await docker.stop(); ``` +#### Health Check / Ping Docker + +Check if the Docker daemon is running and accessible: + +```typescript +// Ping Docker daemon +try { + await docker.ping(); + console.log('✅ Docker is running and accessible'); +} catch (error) { + console.error('❌ Docker is not accessible:', error.message); +} + +// Use in health check function +async function isDockerHealthy(): Promise { + try { + await docker.ping(); + return true; + } catch (error) { + return false; + } +} + +// Example: Wait for Docker to be ready +async function waitForDocker(timeoutMs = 10000): Promise { + const startTime = Date.now(); + + while (Date.now() - startTime < timeoutMs) { + try { + await docker.ping(); + console.log('✅ Docker is ready'); + return; + } catch (error) { + console.log('⏳ Waiting for Docker...'); + await new Promise(resolve => setTimeout(resolve, 1000)); + } + } + + throw new Error('Docker did not become available within timeout'); +} +``` + ### 📦 Container Management #### List All Containers @@ -681,6 +721,7 @@ if (webService && webService.Spec.Mode.Replicated) { ## 🔑 Key Concepts - **DockerHost**: Main entry point for Docker API communication +- **Health Checks**: Use `ping()` method to verify Docker daemon accessibility - **Socket Path Priority**: Constructor option → `DOCKER_HOST` env → CI mode → default socket - **Swarm Mode Required**: Services and secrets require Docker Swarm to be activated - **Type Safety**: Full TypeScript support with comprehensive interfaces diff --git a/ts/00_commitinfo_data.ts b/ts/00_commitinfo_data.ts index 999c1ab..803afdc 100644 --- a/ts/00_commitinfo_data.ts +++ b/ts/00_commitinfo_data.ts @@ -3,6 +3,6 @@ */ export const commitinfo = { name: '@apiclient.xyz/docker', - version: '2.0.0', + version: '2.1.0', description: 'Provides easy communication with Docker remote API from Node.js, with TypeScript support.' } diff --git a/ts/classes.host.ts b/ts/classes.host.ts index c7a4305..f8f71c6 100644 --- a/ts/classes.host.ts +++ b/ts/classes.host.ts @@ -74,6 +74,18 @@ export class DockerHost { await this.imageStore.stop(); } + /** + * Ping the Docker daemon to check if it's running and accessible + * @returns Promise that resolves if Docker is available, rejects otherwise + * @throws Error if Docker ping fails + */ + public async ping(): Promise { + const response = await this.request('GET', '/_ping'); + if (response.statusCode !== 200) { + throw new Error(`Docker ping failed with status ${response.statusCode}`); + } + } + /** * authenticate against a registry * @param userArg