Cleanup

.claude/settings.local.json

@@ -1,27 +1,11 @@
 {
   "permissions": {
     "allow": [
-      "Bash(grep:*)",
-      "Bash(git mv:*)",
-      "Bash(find:*)",
-      "Bash(task proto:*)",
-      "Bash(task protos:*)",
-      "Bash(go mod tidy:*)",
-      "Bash(task build:shim)",
-      "Bash(go test:*)",
-      "Bash(GOOS=linux go test:*)",
-      "Bash(go build:*)",
-      "Bash(go tool cover:*)",
-      "Bash(gofmt:*)",
-      "Bash(golangci-lint run:*)",
-      "Bash(task lint:*)",
-      "Bash(GOOS=linux go build:*)",
-      "Bash(tree:*)",
-      "Bash(wc:*)",
-      "Bash(go doc:*)",
-      "Bash(go list:*)",
-      "Bash(GOOS=linux go vet:*)",
-      "Bash(GOOS=linux task lint:*)"
+      "Bash(*:*)",
+      "Bash(ls:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(payload\" don''t indicate which container failed or which operation,\nmaking troubleshooting difficult.\n\nAdded container ID to all error messages in getCPUStats\\(\\) and\ngetMemoryStats\\(\\) to provide better context for operators:\n- \"missing stats payload\" -> \"container X: missing CPU/memory stats payload\"\n- \"missing CPU/memory stats\" -> \"container X: missing CPU/memory stats in metrics\"\n- Also improved unmarshal error to include context\n\nChanges:\n- internal/shim/resources/vmclient.go: Add containerID to error messages\n\n🤖 Generated with [Claude Code]\\(https://claude.com/claude-code\\)\n\nCo-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>\nEOF\n\\)\")"
     ]
   }
 }

api/VERSIONING.md

@@ -0,0 +1,104 @@
+# API Versioning Policy
+
+## Overview
+
+Qemubox uses semantic versioning for its gRPC/TTRPC APIs to ensure compatibility and smooth upgrades for users.
+
+## Version Format
+
+All API services are versioned using the `/v{N}` suffix in their package names:
+- `containerd.vminitd.services.system.v1`
+- `containerd.vminitd.services.bundle.v1`
+- `containerd.vminitd.services.vmevents.v1`
+
+Where `{N}` is the major version number.
+
+## Compatibility Guarantees
+
+### Within a major version (e.g., v1.0.0 → v1.9.0):
+- **Backward compatible changes only**
+- Can add new:
+  - RPC methods
+  - Message fields (using new field numbers)
+  - Enum values (except renumbering existing ones)
+- Cannot:
+  - Remove or rename existing RPCs
+  - Remove or rename existing message fields
+  - Change field types or numbers
+  - Remove enum values
+
+### Across major versions (e.g., v1 → v2):
+- **Breaking changes allowed**
+- New `/v2` package created alongside `/v1`
+- Both versions can coexist during migration period
+- Deprecated version receives security fixes only
+
+## Adding New Features
+
+### Adding a new RPC method (compatible):
+```protobuf
+service System {
+  rpc Info(google.protobuf.Empty) returns (InfoResponse);  // Existing
+
+  // New method added in v1.2.0
+  rpc GetMetrics(MetricsRequest) returns (MetricsResponse);
+}
+```
+
+### Adding new message fields (compatible):
+```protobuf
+message InfoResponse {
+  string version = 1;          // Existing field
+  string kernel_version = 2;   // Existing field
+
+  // New field added in v1.3.0
+  string hostname = 3;
+}
+```
+
+### Breaking changes require new major version:
+```protobuf
+// OLD: api/services/system/v1/info.proto
+package containerd.vminitd.services.system.v1;
+
+// NEW: api/services/system/v2/info.proto
+package containerd.vminitd.services.system.v2;
+```
+
+## Proto3 Field Evolution
+
+Proto3 provides natural evolution:
+- Unknown fields are preserved during deserialization
+- Clients ignore unknown fields from newer servers
+- Servers ignore unknown fields from older clients
+
+## Deprecation Process
+
+1. **Announce deprecation** in release notes
+2. **Mark deprecated** in proto with comment:
+   ```protobuf
+   // Deprecated: Use NewMethod instead. Will be removed in v2.
+   rpc OldMethod(OldRequest) returns (OldResponse);
+   ```
+3. **Maintain for 2+ minor versions** before major version bump
+4. **Remove in next major version**
+
+## Version Detection
+
+Clients can detect API version via:
+- `Info()` RPC returns `version` field (e.g., "1.2.0")
+- gRPC metadata (if needed for version negotiation)
+
+## Current Version
+
+- **Bundle Service (`bundle/v1`)**: v1.0.0
+- **System Service (`system/v1`)**: v1.0.0
+- **VM Events Service (`vmevents/v1`)**: v1.0.0
+
+All services are currently in v1 and follow backward-compatibility guarantees outlined above.
+
+## References
+
+- [Protobuf Language Guide - Updating](https://protobuf.dev/programming-guides/proto3/#updating)
+- [gRPC Versioning Guide](https://grpc.io/docs/guides/versioning/)
+- [Semantic Versioning 2.0.0](https://semver.org/)

api/services/bundle/v1/bundle.proto

@@ -6,15 +6,33 @@ package containerd.vminitd.services.bundle.v1;
 
 option go_package = "github.com/aledbf/qemubox/containerd/api/services/bundle/v1;bundle";
 
+// Bundle service manages OCI bundle creation inside the VM.
+// This service is exposed by vminitd over vsock to the host shim.
 service Bundle {
+	// Create creates an OCI bundle from the provided files.
+	//
+	// The bundle directory is created at /run/qemubox/{namespace}/{id}/
+	// and populated with the files from the request (e.g., config.json,
+	// hostname, hosts, resolv.conf).
+	//
+	// Returns:
+	//   - INVALID_ARGUMENT: id is empty or files map is empty
+	//   - ALREADY_EXISTS: bundle with this id already exists
+	//   - INTERNAL: failed to create bundle directory or write files
 	rpc Create(CreateRequest) returns (CreateResponse);
 }
 
 message CreateRequest {
+	// id is the unique identifier for the bundle to create.
 	string id = 1;
+
+	// files is a map of filename to file contents.
+	// Keys are relative paths within the bundle (e.g., "config.json", "hosts", "resolv.conf").
+	// Values are the file contents as raw bytes.
 	map<string, bytes> files = 2;
 }
 
 message CreateResponse {
+	// bundle is the absolute path to the created bundle directory on the VM filesystem.
 	string bundle = 1;
 }

api/services/system/v1/info.proto

@@ -8,31 +8,79 @@ import "google/protobuf/empty.proto";
 
 option go_package = "github.com/aledbf/qemubox/containerd/api/services/system/v1;system";
 
+// System service provides VM system information and CPU/memory hotplug operations.
+// This service is exposed by vminitd over vsock to the host shim for dynamic
+// resource management.
 service System {
+	// Info returns VM system information (vminitd version, kernel version).
+	// This is called during VM initialization to verify the guest is ready.
 	rpc Info(google.protobuf.Empty) returns (InfoResponse);
+
+	// OfflineCPU takes a CPU offline via sysfs before hot-unplug.
+	// The CPU must have been previously onlined and cannot be CPU 0 (boot CPU).
+	//
+	// Returns:
+	//   - INVALID_ARGUMENT: cpu_id is 0 (cannot offline boot CPU)
+	//   - NOT_FOUND: cpu_id does not exist in /sys/devices/system/cpu/
+	//   - FAILED_PRECONDITION: CPU is already offline or in use
+	//   - INTERNAL: failed to write to sysfs
 	rpc OfflineCPU(OfflineCPURequest) returns (google.protobuf.Empty);
+
+	// OnlineCPU brings a CPU online via sysfs after hot-plug.
+	// The CPU must have been previously hot-plugged via QEMU QMP.
+	//
+	// Returns:
+	//   - NOT_FOUND: cpu_id does not exist (not yet hot-plugged via QMP)
+	//   - FAILED_PRECONDITION: CPU is already online
+	//   - INTERNAL: failed to write to sysfs
 	rpc OnlineCPU(OnlineCPURequest) returns (google.protobuf.Empty);
+
+	// OfflineMemory takes a memory block offline via sysfs before hot-unplug.
+	//
+	// Returns:
+	//   - NOT_FOUND: memory_id does not exist in /sys/devices/system/memory/
+	//   - FAILED_PRECONDITION: memory block is already offline or contains kernel memory
+	//   - INTERNAL: failed to write to sysfs
 	rpc OfflineMemory(OfflineMemoryRequest) returns (google.protobuf.Empty);
+
+	// OnlineMemory brings a memory block online via sysfs after hot-plug.
+	// The memory block must have been previously hot-plugged via QEMU QMP.
+	//
+	// Returns:
+	//   - NOT_FOUND: memory_id does not exist (not yet hot-plugged via QMP)
+	//   - FAILED_PRECONDITION: memory block is already online
+	//   - INTERNAL: failed to write to sysfs
 	rpc OnlineMemory(OnlineMemoryRequest) returns (google.protobuf.Empty);
 }
 
 message InfoResponse {
+	// version is the qemubox vminitd version (e.g., "1.0.0").
 	string version = 1;
+
+	// kernel_version is the Linux kernel version running in the VM (e.g., "6.1.0").
 	string kernel_version = 2;
 }
 
 message OfflineCPURequest {
+	// cpu_id is the logical CPU ID to offline (zero-indexed, e.g., 0, 1, 2).
+	// This corresponds to /sys/devices/system/cpu/cpu{N}.
 	uint32 cpu_id = 1;
 }
 
 message OnlineCPURequest {
+	// cpu_id is the logical CPU ID to online (zero-indexed, e.g., 0, 1, 2).
+	// This corresponds to /sys/devices/system/cpu/cpu{N}.
 	uint32 cpu_id = 1;
 }
 
 message OfflineMemoryRequest {
+	// memory_id is the memory block ID to offline (zero-indexed).
+	// This corresponds to the QMP memory slot number.
 	uint32 memory_id = 1;
 }
 
 message OnlineMemoryRequest {
+	// memory_id is the memory block ID to online (zero-indexed).
+	// This corresponds to the QMP memory slot number.
 	uint32 memory_id = 1;
 }

cmd/containerd-shim-qemubox-v1/main.go

@@ -10,6 +10,7 @@ import (
 	"github.com/aledbf/qemubox/containerd/internal/config"
 	"github.com/aledbf/qemubox/containerd/internal/shim/manager"
 
+	// Register shim plugin with containerd runtime
 	_ "github.com/aledbf/qemubox/containerd/internal/shim"
 )