docker/readme.hints.md

# 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:
```typescript
// 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:
```typescript
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)