v0.1.7

SSE Events

Last updated


This page describes the Server-Sent Events format QemuRun-pve uses for long-running operations and how to consume it from Go.
Endpoints using SSE: install, start, reboot, set/node.

Event Format


  1. data: {"step":"<stage>","status":"<status>","message":"<message>"}
  2. event: close
  3. data: {}

FieldDescription
stepStep name; the install flow uses <stage> > <step>, see Provisioning Pipeline
statusSee the table below
messageHuman-readable message; finished steps include the duration, e.g. (3.21s)

statusMeaning
processingStep in progress, or a line of qm / init script output (indented by two spaces)
successStep finished
infoFinal notice (start / reboot)
errorStep failed; the flow stops

message prefixMeaning
[*]Info
[+]Success
[-]Failure

Notes


  • Responses are always HTTP 200; read the events to tell success from failure
  • message is built by string concatenation without JSON escaping; when command output contains " or \ that line may not parse as JSON, so clients should skip lines that fail to parse
  • When a pre-check fails (ALLOW_IPS, VM state) you get a single data: {"message": "..."} line with no step / status
  • If the client disconnects, the server-side flow keeps running and simply stops pushing events

Go Client Example


  1. package main
  2. import (
  3. "bufio"
  4. "bytes"
  5. "encoding/json"
  6. "fmt"
  7. "log"
  8. "net/http"
  9. "strings"
  10. )
  11. type event struct {
  12. Step string `json:"step"`
  13. Status string `json:"status"`
  14. Message string `json:"message"`
  15. }
  16. func main() {
  17. body, err := json.Marshal(map[string]any{
  18. "os": "ubuntu",
  19. "version": "24.04",
  20. "cpu": 2,
  21. "ram": 4096,
  22. "disk": "32G",
  23. })
  24. if err != nil {
  25. log.Fatal(err)
  26. }
  27. resp, err := http.Post("http://192.168.0.11:8080/api/vm/install", "application/json", bytes.NewReader(body))
  28. if err != nil {
  29. log.Fatal(err)
  30. }
  31. defer resp.Body.Close()
  32. if resp.StatusCode != http.StatusOK {
  33. log.Fatalf("install rejected: %s", resp.Status)
  34. }
  35. failed := false
  36. scanner := bufio.NewScanner(resp.Body)
  37. for scanner.Scan() {
  38. line := scanner.Text()
  39. if line == "event: close" {
  40. // server-side flow finished
  41. break
  42. }
  43. payload, ok := strings.CutPrefix(line, "data: ")
  44. if !ok {
  45. continue
  46. }
  47. var e event
  48. if err := json.Unmarshal([]byte(payload), &e); err != nil {
  49. // unescaped command output, skip
  50. continue
  51. }
  52. fmt.Printf("[%s] %s %s\n", e.Status, e.Step, e.Message)
  53. if e.Status == "error" {
  54. failed = true
  55. }
  56. }
  57. if err := scanner.Err(); err != nil {
  58. log.Fatal(err)
  59. }
  60. if failed {
  61. log.Fatal("install failed")
  62. }
  63. }
中文