Skip to content

Commit 5b7fa01

Browse files
elibosleyelibosley
committed
feat!: major api improvements (#37)
<!-- This is an auto-generated comment: release notes by coderabbit.ai --> - **New Features** - Introduced asynchronous operations for virtual machine domain management, enabling smoother domain destruction and removal. - Added a new shell script for Docker-based integration testing across multiple architectures. - Added new methods for domain management in the hypervisor context, including domain destruction and undefining. - Introduced a `Domain` class for comprehensive management of virtual machine instances. - Added a new GitHub Actions workflow for automated Docker integration tests across multiple architectures. - **Enhancements** - Improved Docker container configuration with a secure non-root user setup for safer deployments. - Expanded integration tests across multiple architectures and enhanced error handling to provide clearer feedback and improved reliability. - Enhanced XML serialization and deserialization processes for domain configurations, improving robustness against edge cases. - Updated testing framework to utilize Vitest, replacing previous testing tools and enhancing coverage reporting. - Added detailed documentation for several interfaces and enums to improve clarity. - Updated README with new badges and installation instructions, along with a new "Development" section. - **Chores** - Updated CI and dependency management to boost build stability and overall system consistency. - Introduced a new testing configuration for Vitest to streamline test execution and coverage reporting. - Updated system requirements in package management for better compatibility. - Modified `.gitignore` to include new entries for coverage and test artifacts. <!-- end of auto-generated comment: release notes by coderabbit.ai -->
1 parent 39027a6 commit 5b7fa01

33 files changed

Lines changed: 4574 additions & 470 deletions

‎.github/workflows/integration-test.yml‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
name: Docker Integration Tests
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
workflow_dispatch:
9+
10+
jobs:
11+
docker-integration:
12+
name: Docker Integration Tests
13+
runs-on: ubuntu-latest
14+
strategy:
15+
matrix:
16+
arch: [amd64] # arm64 works but is very slow
17+
fail-fast: false
18+
19+
steps:
20+
- name: Checkout code
21+
uses: actions/checkout@v4
22+
23+
- name: Set up Docker Buildx
24+
uses: docker/setup-buildx-action@v3
25+
with:
26+
install: true
27+
28+
- name: Set up QEMU
29+
uses: docker/setup-qemu-action@v3
30+
with:
31+
platforms: linux/amd64,linux/arm64
32+
33+
- name: Create libvirt directories
34+
run: |
35+
sudo mkdir -p /var/run/libvirt
36+
sudo mkdir -p /var/lib/libvirt
37+
sudo chmod -R 777 /var/run/libvirt
38+
sudo chmod -R 777 /var/lib/libvirt
39+
40+
- name: Install dependencies
41+
run: |
42+
sudo apt-get update
43+
sudo apt-get install -y qemu-user-static
44+
45+
- name: Build and run tests
46+
run: |
47+
# Create test artifacts directory
48+
mkdir -p test-artifacts
49+
50+
# Build the Docker image with GitHub Actions cache
51+
docker buildx build \
52+
--platform linux/${{ matrix.arch }} \
53+
--build-arg BASE_IMAGE=node:20-slim \
54+
-t libvirt-test-${{ matrix.arch }} \
55+
--cache-from type=gha \
56+
--cache-to type=gha,mode=max \
57+
--load \
58+
.
59+
60+
# Run the container with necessary privileges
61+
docker run \
62+
--platform linux/${{ matrix.arch }} \
63+
--privileged \
64+
-v /var/run/libvirt/libvirt-sock:/var/run/libvirt/libvirt-sock \
65+
-v /var/lib/libvirt:/var/lib/libvirt \
66+
-v $(pwd)/test-artifacts:/app/test-artifacts \
67+
--name test-container \
68+
libvirt-test-${{ matrix.arch }}
69+
70+
# Copy coverage data from the container
71+
docker cp test-container:/app/coverage ./coverage
72+
docker rm test-container
73+
74+
- name: Upload coverage reports to Codecov
75+
uses: codecov/codecov-action@v5
76+
with:
77+
token: ${{ secrets.CODECOV_TOKEN }}
78+
79+
- name: Upload coverage report
80+
if: always()
81+
uses: actions/upload-artifact@v4
82+
with:
83+
name: coverage-report-${{ matrix.arch }}
84+
path: coverage/
85+
retention-days: 14

‎.github/workflows/main.yml‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ jobs:
3939
- name: Cache APT Packages
4040
uses: awalsh128/cache-apt-pkgs-action@v1.4.3
4141
with:
42-
packages: libvirt-dev
42+
packages: libvirt-dev qemu-system qemu-user-static
4343
version: 1.0
4444

4545
- name: Set Node.js
@@ -72,8 +72,11 @@ jobs:
7272
- name: Build
7373
run: pnpm run build
7474

75-
- name: test
76-
run: pnpm run test
75+
- name: Set up Docker Buildx
76+
uses: docker/setup-buildx-action@v3
77+
with:
78+
install: true
79+
7780

7881
- name: Setup NPM Authentication
7982
if: ${{ needs.release-please.outputs.release_created }}

‎.gitignore‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,4 +10,9 @@
1010
*.tgz
1111

1212
# tsbuildinfo
13-
tsconfig.tsbuildinfo
13+
tsconfig.tsbuildinfo
14+
15+
# coverage
16+
coverage
17+
18+
test-artifacts/

‎Dockerfile‎

Lines changed: 85 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,90 @@
1-
FROM node:22-bookworm-slim AS development
2-
# Install build tools
3-
RUN apt-get update -y && apt-get install -y \
1+
# Build stage
2+
FROM node:20-slim AS builder
3+
4+
# Prevent interactive prompts during package installation
5+
ENV DEBIAN_FRONTEND=noninteractive
6+
7+
# Install build dependencies
8+
RUN apt-get update && apt-get install -y \
9+
build-essential \
410
python3 \
511
libvirt-dev \
6-
jq
12+
&& rm -rf /var/lib/apt/lists/*
13+
14+
# Set up the build environment
15+
WORKDIR /app
16+
17+
# Copy package files first to leverage caching
18+
COPY package*.json ./
19+
COPY pnpm-lock.yaml ./
720

8-
# Install pnpm globally using npm
9-
RUN npm install -g pnpm@latest
21+
# Install pnpm and dependencies
22+
RUN npm install -g pnpm && \
23+
pnpm install --frozen-lockfile
1024

25+
# Copy source files
26+
COPY . .
27+
28+
# Build the project
29+
RUN pnpm run build
30+
31+
# Test stage
32+
FROM node:20-slim AS test
33+
34+
# Prevent interactive prompts during package installation
35+
ENV DEBIAN_FRONTEND=noninteractive
36+
37+
# Install test dependencies
38+
RUN apt-get update && apt-get install -y \
39+
build-essential \
40+
python3 \
41+
qemu-system-x86 \
42+
qemu-system-arm \
43+
qemu-efi \
44+
qemu-efi-aarch64 \
45+
qemu-utils \
46+
ovmf \
47+
libvirt-daemon-system \
48+
libvirt-dev \
49+
&& rm -rf /var/lib/apt/lists/*
50+
51+
# Create a non-root user for libvirt and set up permissions
52+
RUN useradd -m -s /bin/bash -g libvirt libvirt && \
53+
usermod -aG kvm libvirt && \
54+
mkdir -p /var/run/libvirt && \
55+
chown root:libvirt /var/run/libvirt && \
56+
chmod g+w /var/run/libvirt
57+
58+
# Set up the test environment
1159
WORKDIR /app
60+
61+
# Copy package files and install all dependencies (including dev)
62+
COPY package*.json ./
63+
COPY pnpm-lock.yaml ./
64+
RUN npm install -g pnpm && \
65+
pnpm install --frozen-lockfile
66+
67+
# Copy built files and test files from builder stage
68+
COPY --from=builder /app/dist ./dist
69+
COPY --from=builder /app/lib ./lib
70+
COPY --from=builder /app/__tests__ ./__tests__
71+
COPY --from=builder /app/vitest.config.ts ./vitest.config.ts
72+
COPY --from=builder /app/build ./build
73+
74+
# Set up libvirt configuration
75+
RUN mkdir -p /etc/libvirt && \
76+
echo 'unix_sock_group = "libvirt"' >> /etc/libvirt/libvirtd.conf && \
77+
echo 'unix_sock_rw_perms = "0770"' >> /etc/libvirt/libvirtd.conf && \
78+
echo 'auth_unix_rw = "none"' >> /etc/libvirt/libvirtd.conf
79+
80+
# Create necessary directories with correct permissions
81+
RUN mkdir -p /home/libvirt/.config/libvirt && \
82+
echo 'uri_default = "qemu:///session"' > /home/libvirt/.config/libvirt/libvirt.conf && \
83+
chown -R libvirt:libvirt /home/libvirt/.config && \
84+
chown -R libvirt:libvirt /app
85+
86+
# Switch to non-root user
87+
USER libvirt
88+
89+
# Start libvirtd and run tests
90+
CMD ["/bin/sh", "-c", "/usr/sbin/libvirtd --daemon && sleep 2 && pnpm test:coverage"]

‎README.md‎

Lines changed: 71 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -4,10 +4,14 @@
44

55
![Alpha badge][alphabadge]
66
![CI badge][cibadge]
7+
![Tests badge][testsbadge]
8+
![Codecov badge][codecovbadge]
79
![License badge][licensebadge]
810
![Contributors badge][contribadge]
911
![Issues badge][issuesbadge]
1012
![PR badge][prbadge]
13+
![NPM Version][npmbadge]
14+
![Last Update][lastcommitbadge]
1115

1216
Libvirt bindings for Node.js®.
1317

@@ -77,7 +81,7 @@ const hypervisor = new libvirt.Hypervisor({ uri });
7781
### Debian / Ubuntu
7882

7983
```bash
80-
sudo apt install build-essential libvirt-dev
84+
sudo apt install build-essential libvirt-dev qemu-system
8185
npm i @unraid/libvirt
8286
```
8387

@@ -86,21 +90,71 @@ npm i @unraid/libvirt
8690
Install Homebrew and Xcode first if not already installed.
8791

8892
```bash
89-
brew install libvirt
93+
brew install libvirt qemu
9094
npm i @unraid/libvirt
9195
```
9296

97+
## Development
98+
99+
This project uses pnpm as the package manager. Make sure you have it installed:
100+
101+
```bash
102+
npm install -g pnpm
103+
```
104+
105+
### Building
106+
107+
```bash
108+
pnpm install
109+
pnpm build
110+
```
111+
112+
### Testing
113+
114+
The project uses Vitest for testing. You can run tests using:
115+
116+
```bash
117+
# Run tests
118+
pnpm test
119+
120+
# Run tests with coverage
121+
pnpm test:coverage
122+
123+
# Run tests with UI
124+
pnpm test:ui
125+
```
126+
127+
### Examples
128+
129+
The project includes several example scripts that demonstrate different features:
130+
131+
```bash
132+
# List all domains
133+
pnpm examples/list
134+
135+
# Start a domain
136+
pnpm examples/start
137+
138+
# Shutdown a domain
139+
pnpm examples/shutdown
140+
141+
# Create a domain using the builder pattern
142+
pnpm examples/builder
143+
```
144+
93145
## Contribute
94146

95-
Any contribution is welcome! To check wether your contribution conforms our style guide run the following tasks:
147+
Any contribution is welcome! To check whether your contribution conforms to our style guide, run the following tasks:
96148

97149
```bash
98-
pip install cppcheck # required once
99-
git submodule update --init --recursive # required once
150+
# Install dependencies
151+
pnpm install
152+
153+
# Run linting
154+
pnpm lint
100155

101-
pnpm run lint/bindings
102-
pnpm run lint/lib
103-
pnpm run lint/examples
156+
# Run tests
157+
pnpm test
104158
```
105159

106160
---
@@ -129,8 +183,12 @@ SOFTWARE.
129183

130184
[cover]: cover.png "Cover image"
131185
[alphabadge]: https://img.shields.io/badge/-alpha-green "Alpha badge"
132-
[licensebadge]: https://img.shields.io/github/license/vmngr/libvirt "License badge"
133-
[cibadge]: https://github.com/vmngr/libvirt/workflows/CI/badge.svg "CI badge"
134-
[contribadge]: https://img.shields.io/github/contributors/vmngr/libvirt "Contributors badge"
135-
[issuesbadge]: https://img.shields.io/github/issues/vmngr/libvirt "Issues badge"
136-
[prbadge]: https://img.shields.io/github/issues-pr/vmngr/libvirt "PR badge"
186+
[licensebadge]: https://img.shields.io/github/license/unraid/libvirt "License badge"
187+
[cibadge]: https://github.com/unraid/libvirt/workflows/CI/badge.svg "CI badge"
188+
[testsbadge]: https://img.shields.io/github/actions/workflow/status/unraid/libvirt/integration-test.yml?label=tests "Tests badge"
189+
[codecovbadge]: https://codecov.io/gh/unraid/libvirt/branch/main/graph/badge.svg "Codecov badge"
190+
[contribadge]: https://img.shields.io/github/contributors/unraid/libvirt "Contributors badge"
191+
[issuesbadge]: https://img.shields.io/github/issues/unraid/libvirt "Issues badge"
192+
[prbadge]: https://img.shields.io/github/issues-pr/unraid/libvirt "PR badge"
193+
[npmbadge]: https://img.shields.io/npm/v/@unraid/libvirt "NPM Version badge"
194+
[lastcommitbadge]: https://img.shields.io/github/last-commit/unraid/libvirt "Last Commit badge"

0 commit comments

Comments
 (0)