Subscribing to post-build events

Determinate Nixd exposes a streaming HTTP API of server-sent events (SSE) to enable 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. The relevant event for post-build events is BuiltPathResponseEventV1.

You can select for this event by expecting:

The v key to equal the string 1
The c key to equal the string BuiltPathResponseEventV1

The drv key contains the full path to the derivation that completed building. The outputs key contains an array of all the outputs that were produced. Failed builds do not produce a post-build event.

Here’s an example JSON event:

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

Example response stream

In one terminal, open the socket with curl:

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

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

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

You should see a BuiltPathResponseEventV1 event following the completion of the --rebuild:

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

* 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"]}