30 lines
1.8 KiB
Markdown
30 lines
1.8 KiB
Markdown
# Project Hints
|
|
|
|
## Architecture
|
|
- Wraps Amazon Firecracker VMM using HTTP-over-Unix-socket API
|
|
- Uses `@push.rocks/smartrequest` with URL format `http://unix:<socket>:<path>` for socket communication
|
|
- Uses `@push.rocks/smartshell` `execStreaming()` to manage Firecracker child processes
|
|
- Uses `@push.rocks/smartexit` for cleanup on process exit
|
|
- `BaseImageManager` downloads Firecracker CI demo artifacts or hosted project manifests into `/tmp/.smartvm/base-images` by default
|
|
- Base image cache keeps 2 bundles by default and warns before evicting older bundles
|
|
- Hosted manifest examples live in `assets/base-images/`
|
|
- VM runtime files default to `/dev/shm/.smartvm/runtime` when available
|
|
- Writable drives are staged into per-VM runtime storage by default and removed during cleanup; use `ephemeral: false` only for explicit persistence
|
|
|
|
## Key API Patterns
|
|
- SmartRequest: `SmartRequest.create().url(...).json(body).put()` — response has `.status`, `.ok`, `.json()`
|
|
- Smartshell: `shell.execStreaming(cmd)` returns `{ childProcess, terminate(), kill(), finalPromise }`
|
|
- SmartExit: `smartExit.addProcess(child)`, `smartExit.addCleanupFunction(fn)`, `smartExit.killAll()`
|
|
|
|
## Firecracker API
|
|
- Pre-boot config: PUT /boot-source, PUT /machine-config, PUT /drives/{id}, PUT /network-interfaces/{id}
|
|
- Start: PUT /actions { action_type: "InstanceStart" }
|
|
- Pause/Resume: PATCH /vm { state: "Paused" | "Resumed" }
|
|
- Stop: PUT /actions { action_type: "SendCtrlAltDel" }
|
|
|
|
## Integration Testing
|
|
- Default `pnpm test` skips real Firecracker boot testing
|
|
- Set `SMARTVM_RUN_INTEGRATION=true` to run the opt-in boot test
|
|
- `SMARTVM_BASE_IMAGE_PRESET` supports `latest` and `lts`; default is `latest`
|
|
- Hosted/project-owned bundles use `baseImageManifestUrl`, `baseImageManifestPath`, `manifestUrl`, or `manifestPath`
|