Subscribing to Determinate Nixd’s post-build events

Determinate Nixd provides a streaming HTTP API for server-sent events (SSE) that enables applications to act on completed builds.

Determinate Nixd listens on the socket at /nix/var/determinate/determinate-nixd.socket.

Payload structure

The event stream can send a variety of JSON-formatted events and it’s important to ignore unexpected events. You can select for the event type by expecting:

The v key to equal the string 1
The c key to equal one of these event names:
The other fields to depend on the event type

Here’s an example JSON event of type BuiltPathResponseEventV1:


{
  "v": "1",
  "c": "BuiltPathResponseEventV1",
  "drv": "/nix/store/apdrfapx7hrx45az67g1i2k0kvixg1av-hello-2.12.1.drv",
  "outputs": [
    "/nix/store/lwld8afww62dcd97kwdnwwvv0bh5mqf1-hello-2.12.1"
  ]
}

Event types

This section provides an exhaustive list of Determinate Nixd’s post-build events. This list is likely to expand and change over time.

`BuildFailureResponseEventV1`

Determinate Nixd emits this type of event when realisation fails.

Parameter	Type	Description
`drv`	Path	The full Nix store path to the derivation for which the build failed
`provenance`	Provenance (optional)	An object describing the store path’s provenance
`timing`	Timing (optional)	Information about the time required by the build

`BuiltPathResponseEventV1`

Determinate Nixd emits this type of event when realisation succeeds.

Parameter	Type	Description
`drv`	Path	The full Nix store path to the derivation for which the build completed
`outputs`	List of paths	An array of Nix store paths for all of the outputs produced by the build
`provenance`	Provenance (optional)	An object describing the store path’s provenance
`timing`	Timing (optional)	Information about the time required by the build

`HashMismatchResponseEventV1`

Determinate Nixd emits this type of event when realisation fails due to a hash mismatch. These events are always accompanied by a BuildFailureResponseEventV1.

Parameter	Type	Description
`drv`	Path	The full Nix store path to the derivation for which a hash mismatch was detected
`bad`	List of strings (optional)	The incorrect hashes encountered during the build
`good`	String	The correct (“good”) hash calculated by Nix

This event type is used by Determinate Nixd to fix incorrect hashes.

Secondary data types

Timing

Parameter	Type	Description
`startTime`	UTC timestamp	The operation’s start time
`stopTime`	UTC timestamp	The operation’s stop time
`durationSeconds`	Integer	The number of seconds the operation took in total (the difference between `stopTime` and `startTime`)

Provenance

This object contains all of the provenance-related information provided by the Determinate Nix CLI. The structure of this object is currently unstable.

Response stream listening example

This section shows you how to listen for Determinate Nixd events using cURL. In one terminal, open the socket:


curl -nLv --unix-socket /nix/var/determinate/determinate-nixd.socket http://localhost/events

In another terminal, build (and rebuild) the hello package from Nixpkgs:


nix build nixpkgs#hello
nix build nixpkgs#hello --rebuild

In the terminal in which you ran the cURL command, you should see a BuiltPathResponseEventV1 event following the completion of the --rebuild:


* Couldn't find host localhost in the .netrc file; using defaults
*   Trying /nix/var/determinate/determinate-nixd.socket:0...
* Connected to localhost (/nix/var/determinate/determinate-nixd.socket) port 80
> GET /events HTTP/1.1
> Host: localhost
> User-Agent: curl/8.6.0
> Accept: */*
>
< HTTP/1.1 200 OK
< content-type: text/event-stream
< cache-control: no-cache
< transfer-encoding: chunked
< date: Wed, 28 Aug 2024 02:36:04 GMT
<

:

data: {"v":"1","c":"BuiltPathResponseEventV1","drv":"/nix/store/apdrfapx7hrx45az67g1i2k0kvixg1av-hello-2.12.1.drv","outputs":["/nix/store/lwld8afww62dcd97kwdnwwvv0bh5mqf1-hello-2.12.1"]}