-
Notifications
You must be signed in to change notification settings - Fork 1
Expand file tree
/
Copy pathtypes.go
More file actions
249 lines (220 loc) · 7.93 KB
/
Copy pathtypes.go
File metadata and controls
249 lines (220 loc) · 7.93 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
// Package kernel implements Boatstack's domain-neutral supervisory-control
// mechanism. Domain packages supply observations, transition predicates, and
// operators; the kernel owns freshness, authority, selection, verification,
// state revision, and receipts.
package kernel
import (
"crypto/sha256"
"encoding/hex"
"encoding/json"
"fmt"
"regexp"
"sort"
"time"
)
const (
ProgramSchemaVersion = 1
PrescriptionSchemaVersion = 2
ReceiptSchemaVersion = 3
)
var (
semanticID = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9._-]*$`)
qualifiedSemanticID = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9._-]*(?:/[A-Za-z0-9][A-Za-z0-9._-]*)*$`)
)
// Objective is an external reference. It is not supervisory state.
type Objective struct {
ID string `json:"id"`
Revision uint64 `json:"revision"`
Fingerprint string `json:"fingerprint"`
Reference json.RawMessage `json:"reference"`
}
func NewObjective(id string, revision uint64, reference any) (Objective, error) {
encoded, err := json.Marshal(reference)
if err != nil {
return Objective{}, err
}
objective := Objective{ID: id, Revision: revision, Reference: encoded}
fingerprint, err := contentHash(struct {
ID string `json:"id"`
Revision uint64 `json:"revision"`
Reference json.RawMessage `json:"reference"`
}{objective.ID, objective.Revision, objective.Reference})
if err != nil {
return Objective{}, err
}
objective.Fingerprint = fingerprint
return objective, objective.Validate()
}
func (o Objective) Validate() error {
if !semanticID.MatchString(o.ID) || o.Revision == 0 || len(o.Fingerprint) != 64 || len(o.Reference) == 0 || !json.Valid(o.Reference) {
return fmt.Errorf("objective requires semantic identity, positive revision, canonical reference, and fingerprint")
}
fingerprint, err := contentHash(struct {
ID string `json:"id"`
Revision uint64 `json:"revision"`
Reference json.RawMessage `json:"reference"`
}{o.ID, o.Revision, o.Reference})
if err != nil || fingerprint != o.Fingerprint {
return fmt.Errorf("objective fingerprint does not identify its exact revision")
}
return nil
}
// ObjectiveBinding is the only objective material retained in supervisory
// state. It binds an exact immutable objective revision.
type ObjectiveBinding struct {
ObjectiveID string `json:"objective_id"`
ObjectiveRevision uint64 `json:"objective_revision"`
ObjectiveFingerprint string `json:"objective_fingerprint"`
}
func BindObjective(objective Objective) (ObjectiveBinding, error) {
if err := objective.Validate(); err != nil {
return ObjectiveBinding{}, err
}
return ObjectiveBinding{objective.ID, objective.Revision, objective.Fingerprint}, nil
}
func (b ObjectiveBinding) Validate() error {
if !semanticID.MatchString(b.ObjectiveID) || b.ObjectiveRevision == 0 || len(b.ObjectiveFingerprint) != 64 {
return fmt.Errorf("objective binding requires exact identity, revision, and fingerprint")
}
return nil
}
func (b ObjectiveBinding) Matches(objective Objective) bool {
return objective.Validate() == nil && b.ObjectiveID == objective.ID && b.ObjectiveRevision == objective.Revision && b.ObjectiveFingerprint == objective.Fingerprint
}
type ProgramIdentity struct {
ID string `json:"id"`
Version string `json:"version"`
Fingerprint string `json:"fingerprint"`
}
func (p ProgramIdentity) Validate() error {
if !semanticID.MatchString(p.ID) || p.Version == "" || len(p.Fingerprint) != 64 {
return fmt.Errorf("program identity requires id, version, and fingerprint")
}
return nil
}
// ControlState is durable supervisory state. Domain state is deliberately not
// embedded here; it is supplied as a canonical observation by a Domain.
type ControlState struct {
InstanceID string `json:"instance_id"`
Program ProgramIdentity `json:"program"`
ObjectiveBinding *ObjectiveBinding `json:"objective_binding,omitempty"`
Mode string `json:"mode"`
Revision uint64 `json:"revision"`
Recovery *RecoveryState `json:"recovery,omitempty"`
}
type RecoveryState struct {
PrescriptionID string `json:"prescription_id"`
TransitionID string `json:"transition_id"`
Reason string `json:"reason"`
}
func (s ControlState) Validate() error {
if !semanticID.MatchString(s.InstanceID) || s.Mode == "" || s.Revision == 0 {
return fmt.Errorf("control state requires instance, mode, and positive revision")
}
if err := s.Program.Validate(); err != nil {
return err
}
if s.ObjectiveBinding != nil {
if err := s.ObjectiveBinding.Validate(); err != nil {
return err
}
}
if s.Recovery != nil && (s.Recovery.PrescriptionID == "" || !qualifiedSemanticID.MatchString(s.Recovery.TransitionID) || s.Recovery.Reason == "") {
return fmt.Errorf("recovery state is incomplete")
}
return nil
}
type ObjectiveScope string
const (
ObjectiveNone ObjectiveScope = "none"
ObjectiveOptionalPreserve ObjectiveScope = "optional-preserve"
ObjectiveBoundExact ObjectiveScope = "bound-exact"
)
func (s ObjectiveScope) Valid() bool {
return s == ObjectiveNone || s == ObjectiveOptionalPreserve || s == ObjectiveBoundExact
}
type Capability string
func (c Capability) Validate() error {
if !semanticID.MatchString(string(c)) {
return fmt.Errorf("capability %q is not a semantic identifier", c)
}
return nil
}
type AuthorityReceipt struct {
ID string `json:"id"`
Subject string `json:"subject"`
Fingerprint string `json:"fingerprint"`
Capabilities []Capability `json:"capabilities"`
IssuedAt time.Time `json:"issued_at"`
ExpiresAt time.Time `json:"expires_at,omitempty"`
}
func (r AuthorityReceipt) Validate(now time.Time) error {
if !semanticID.MatchString(r.ID) || r.Subject == "" || r.Fingerprint == "" || r.IssuedAt.IsZero() || r.IssuedAt.After(now) || (!r.ExpiresAt.IsZero() && !now.Before(r.ExpiresAt)) {
return fmt.Errorf("authority receipt %q is invalid or expired", r.ID)
}
if len(r.Capabilities) == 0 {
return fmt.Errorf("authority receipt %q grants no capabilities", r.ID)
}
_, err := normalizeCapabilities(r.Capabilities)
return err
}
type Authority struct {
Receipts []AuthorityReceipt `json:"receipts"`
}
func (a Authority) projection(now time.Time) (authorityProjection, error) {
receipts := append([]AuthorityReceipt(nil), a.Receipts...)
sort.Slice(receipts, func(i, j int) bool { return receipts[i].ID < receipts[j].ID })
seen := map[string]bool{}
var capabilities []Capability
for _, receipt := range receipts {
if err := receipt.Validate(now); err != nil {
return authorityProjection{}, err
}
if seen[receipt.ID] {
return authorityProjection{}, fmt.Errorf("authority receipt %q is duplicated", receipt.ID)
}
seen[receipt.ID] = true
capabilities = append(capabilities, receipt.Capabilities...)
}
capabilities, err := normalizeCapabilities(capabilities)
if err != nil {
return authorityProjection{}, err
}
fingerprint, err := contentHash(receipts)
return authorityProjection{Fingerprint: fingerprint, Capabilities: capabilities}, err
}
type authorityProjection struct {
Fingerprint string
Capabilities []Capability
}
type EffectFact struct {
Facet string `json:"facet"`
Operation string `json:"operation"`
Fingerprint string `json:"fingerprint"`
}
type Effect struct {
Facts []EffectFact `json:"facts"`
}
func normalizeCapabilities(values []Capability) ([]Capability, error) {
seen := map[Capability]bool{}
for _, value := range values {
if err := value.Validate(); err != nil {
return nil, err
}
seen[value] = true
}
result := make([]Capability, 0, len(seen))
for value := range seen {
result = append(result, value)
}
sort.Slice(result, func(i, j int) bool { return result[i] < result[j] })
return result, nil
}
func contentHash(value any) (string, error) {
encoded, err := json.Marshal(value)
if err != nil {
return "", err
}
digest := sha256.Sum256(encoded)
return hex.EncodeToString(digest[:]), nil
}