Skip to content

Commit 144c662

Browse files
Ericson2314Ericson2314
committed
JSON Schema for build trace entry
Note, starting to make progress on #11895 by calling it this in the manual.
1 parent 72d0f7b commit 144c662

File tree

10 files changed

+117
-1
lines changed

10 files changed

+117
-1
lines changed

‎doc/manual/package.nix‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,7 @@ mkMesonDerivation (finalAttrs: {
3737
../../src/libutil-tests/data/hash
3838
../../src/libstore-tests/data/content-address
3939
../../src/libstore-tests/data/store-path
40+
../../src/libstore-tests/data/realisation
4041
../../src/libstore-tests/data/derived-path
4142
../../src/libstore-tests/data/path-info
4243
../../src/libstore-tests/data/nar-info

‎doc/manual/source/SUMMARY.md.in‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -126,6 +126,7 @@
126126
- [Store Object Info](protocols/json/store-object-info.md)
127127
- [Derivation](protocols/json/derivation.md)
128128
- [Deriving Path](protocols/json/deriving-path.md)
129+
- [Build Trace Entry](protocols/json/build-trace-entry.md)
129130
- [Serving Tarball Flakes](protocols/tarball-fetcher.md)
130131
- [Store Path Specification](protocols/store-path.md)
131132
- [Nix Archive (NAR) Format](protocols/nix-archive/index.md)

‎doc/manual/source/protocols/json/build-trace-entry.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
{{#include build-trace-entry-v1-fixed.md}}
2+
3+
## Examples
4+
5+
### Simple build trace entry
6+
7+
```json
8+
{{#include schema/build-trace-entry-v1/simple.json}}
9+
```
10+
11+
### Build trace entry with dependencies
12+
13+
```json
14+
{{#include schema/build-trace-entry-v1/with-dependent-realisations.json}}
15+
```
16+
17+
### Build trace entry with signature
18+
19+
```json
20+
{{#include schema/build-trace-entry-v1/with-signature.json}}
21+
```
22+
23+
<!--
24+
## Raw Schema
25+
26+
[JSON Schema for Build Trace Entry v1](schema/build-trace-entry-v1.json)
27+
-->

‎doc/manual/source/protocols/json/meson.build‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ schemas = [
1515
'store-object-info-v1',
1616
'derivation-v3',
1717
'deriving-path-v1',
18+
'build-trace-entry-v1',
1819
]
1920

2021
schema_files = files()

‎doc/manual/source/protocols/json/schema/build-trace-entry-v1‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../../../../../src/libstore-tests/data/realisation

‎doc/manual/source/protocols/json/schema/build-trace-entry-v1.yaml‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
"$schema": "http://json-schema.org/draft-04/schema"
2+
"$id": "https://nix.dev/manual/nix/latest/protocols/json/schema/build-trace-entry-v1.json"
3+
title: Build Trace Entry
4+
description: |
5+
A record of a successful build outcome for a specific derivation output.
6+
7+
This schema describes the JSON representation of a [build trace entry](@docroot@/store/build-trace.md) entry.
8+
9+
> **Warning**
10+
>
11+
> This JSON format is currently
12+
> [**experimental**](@docroot@/development/experimental-features.md#xp-feature-ca-derivations)
13+
> and subject to change.
14+
15+
type: object
16+
required:
17+
- id
18+
- outPath
19+
- dependentRealisations
20+
- signatures
21+
properties:
22+
id:
23+
type: string
24+
title: Derivation Output ID
25+
pattern: "^sha256:[0-9a-f]{64}![a-zA-Z_][a-zA-Z0-9_-]*$"
26+
description: |
27+
Unique identifier for the derivation output that was built.
28+
29+
Format: `{hash-quotient-drv}!{output-name}`
30+
31+
- **hash-quotient-drv**: SHA-256 [hash of the quotient derivation](@docroot@/store/derivation/outputs/input-address.md#hash-quotient-drv).
32+
Begins with `sha256:`.
33+
34+
- **output-name**: Name of the specific output (e.g., "out", "dev", "doc")
35+
36+
Example: `"sha256:ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad!foo"`
37+
38+
outPath:
39+
"$ref": "store-path-v1.yaml"
40+
title: Output Store Path
41+
description: |
42+
The path to the store object that resulted from building this derivation for the given output name.
43+
44+
dependentRealisations:
45+
type: object
46+
title: Underlying Base Build Trace
47+
description: |
48+
This is for [*derived*](@docroot@/store/build-trace.md#derived) build trace entries to ensure coherence.
49+
50+
Keys are derivation output IDs (same format as the main `id` field).
51+
Values are the store paths that those dependencies resolved to.
52+
53+
As described in the linked section on derived build trace traces, derived build trace entries must be kept in addition and not instead of the underlying base build entries.
54+
This is the set of base build trace entries that this derived build trace is derived from.
55+
(The set is also a map since this miniature base build trace must be coherent, mapping each key to a single value.)
56+
57+
patternProperties:
58+
"^sha256:[0-9a-f]{64}![a-zA-Z_][a-zA-Z0-9_-]*$":
59+
$ref: "store-path-v1.yaml"
60+
title: Dependent Store Path
61+
description: Store path that this dependency resolved to during the build
62+
additionalProperties: false
63+
64+
signatures:
65+
type: array
66+
title: Build Signatures
67+
description: |
68+
A set of cryptographic signatures attesting to the authenticity of this build trace entry.
69+
items:
70+
type: string
71+
title: Signature
72+
description: A single cryptographic signature
73+
74+
additionalProperties: false

‎doc/manual/source/store/build-trace.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ And even in that case, a different result doesn't mean the original entry was a
2929
As such, the decision of whether to trust a counterparty's build trace is a fundamentally subject policy choice.
3030
Build trace entries are typically *signed* in order to enable arbitrary public-key-based trust polices.
3131

32-
## Derived build traces
32+
## Derived build traces {#derived}
3333

3434
Implementations that wish to memoize the above may also keep additional *derived* build trace entries that do map unresolved derivations.
3535
But if they do so, they *must* also keep the underlying base entries with resolved derivation keys around.

‎src/json-schema-checks/build-trace-entry‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../src/libstore-tests/data/realisation

‎src/json-schema-checks/meson.build‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,15 @@ schemas = [
5454
'single_built_built.json',
5555
],
5656
},
57+
{
58+
'stem' : 'build-trace-entry',
59+
'schema' : schema_dir / 'build-trace-entry-v1.yaml',
60+
'files' : [
61+
'simple.json',
62+
'with-dependent-realisations.json',
63+
'with-signature.json',
64+
],
65+
},
5766
]
5867

5968
# Derivation and Derivation output

‎src/json-schema-checks/package.nix‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ mkMesonDerivation (finalAttrs: {
2323
../../src/libutil-tests/data/hash
2424
../../src/libstore-tests/data/content-address
2525
../../src/libstore-tests/data/store-path
26+
../../src/libstore-tests/data/realisation
2627
../../src/libstore-tests/data/derivation
2728
../../src/libstore-tests/data/derived-path
2829
../../src/libstore-tests/data/path-info

0 commit comments

Comments
 (0)