Docker Module - Development Hints

Dependency Upgrade Notes (2026-03-28 - v5.2.0)

Major Upgrades Completed

Package	From	To	Notes
@push.rocks/smartfile	^11.2.7	^13.1.2	`fs.`, `fsStream.` removed; use `node:fs` directly or `SmartFileFactory.nodeFs()`
@push.rocks/smartarchive	^4.2.2	^5.2.1	`SmartArchive.fromArchiveFile()` removed; use `SmartArchive.create().file(path).extract(dir)`
@push.rocks/smartbucket	^3.3.10	^4.5.1	Strict-by-default: `fastPutStream` throws on existing objects instead of overwriting
@push.rocks/smartjson	^5.2.0	^6.0.0	No code changes needed
@push.rocks/smartnetwork	^4.4.0	^4.5.2	v4.5.2 uses Rust bridge for getDefaultGateway; breaks in Deno without --allow-run
@tsclass/tsclass	^9.3.0	^9.5.0	No code changes needed
@git.zone/tsbuild	^3.1.0	^4.4.0	v4.4.0 enforces strict TS checks (strictPropertyInitialization)
@git.zone/tstest	^2.8.2	^3.6.3	No code changes needed
@types/node	^22.15.0	^25.5.0	Major version bump

Migration Details

smartfile v13: All smartfile.fs.* and smartfile.fsStream.* APIs were removed. Replaced with:

plugins.fs.createReadStream() / plugins.fs.createWriteStream() (from node:fs)
plugins.fs.promises.rm() (for file/dir removal)
plugins.fs.existsSync() (for file existence checks)
plugins.smartfile.SmartFileFactory.nodeFs().fromFilePath() (for reading files into SmartFile objects)

smartarchive v5: Uses fluent API now:

// Old: SmartArchive.fromArchiveFile(path) -> archive.exportToFs(dir)
// New: SmartArchive.create().file(path).extract(dir)

// TarTools: packDirectory() now returns Uint8Array, use getDirectoryPackStream() for streams

smartbucket v4: fastPutStream now throws if object already exists. Must delete first:

try { await dir.fastRemove({ path }); } catch (e) { /* may not exist */ }
await dir.fastPutStream({ stream, path });

tsbuild v4.4.0: Enforces strictPropertyInitialization. All class properties populated via Object.assign() from Docker API responses need ! definite assignment assertions.

smartnetwork v4.5.2: getDefaultGateway() now uses a Rust binary bridge. Fails in Deno without --allow-run permission. Code wraps the call in try/catch with fallback to empty string (Docker auto-detects advertise address).

Config Migration

npmextra.json renamed to .smartconfig.json
Removed stale npmdocker and duplicate gitzone sections
@push.rocks/smartfs removed (was imported but never used)

OCI Image Format Handling

The DockerImageStore.storeImage() method handles optional repositories file gracefully. OCI-format image tars may not include this file, so it's checked with fs.existsSync() before attempting to read.

Architecture

DockerHost is the single entry point (Facade pattern)
All resource classes extend abstract DockerResource base class
Static methods prefixed with _ indicate internal use
Public API exclusively through DockerHost methods

Key Patterns

Factory pattern: All resource creation/retrieval goes through DockerHost
Stream handling: Web ReadableStreams from smartrequest are converted to Node.js streams via smartstream.nodewebhelpers
Container getter: Uses list+filter pattern (not direct API call) to avoid creating invalid objects from error responses

Test Notes

Tests are nonci (require Docker daemon)
S3 imagestore test can take 2-3 minutes depending on network
Exec tests use 5s safety timeout due to buildkit container not always emitting stream 'end' events
Test timeout is 600s to accommodate slow S3 uploads
Deno tests crash with smartnetwork v4.5.2 due to Rust binary spawn permissions (not a code bug)

3.7 KiB Raw Permalink Blame History