1package dag
2
3import (
4 "crypto/rand"
5 "encoding/json"
6 "fmt"
7 "time"
8
9 "github.com/pkg/errors"
10
11 "github.com/git-bug/git-bug/entities/identity"
12 "github.com/git-bug/git-bug/entity"
13 "github.com/git-bug/git-bug/repository"
14)
15
16// OperationType is an operation type identifier
17type OperationType int
18
19// Operation is a piece of data defining a change to reflect on the state of an Entity.
20// What this Operation or Entity's state looks like is not of the resort of this package as it only deals with the
21// data structure and storage.
22type Operation interface {
23 // Id return the Operation identifier
24 //
25 // Some care need to be taken to define a correct Id derivation and enough entropy in the data used to avoid
26 // collisions. Notably:
27 // - the Id of the first Operation will be used as the Id of the Entity. Collision need to be avoided across entities
28 // of the same type (example: no collision within the "bug" namespace).
29 // - collisions can also happen within the set of Operations of an Entity. Simple Operation might not have enough
30 // entropy to yield unique Ids (example: two "close" operation within the same second, same author).
31 // If this is a concern, it is recommended to include a piece of random data in the operation's data, to guarantee
32 // a minimal amount of entropy and avoid collision.
33 //
34 // Author's note: I tried to find a clever way around that inelegance (stuffing random useless data into the stored
35 // structure is not exactly elegant), but I failed to find a proper way. Essentially, anything that would reuse some
36 // other data (parent operation's Id, lamport clock) or the graph structure (depth) impose that the Id would only
37 // make sense in the context of the graph and yield some deep coupling between Entity and Operation. This in turn
38 // make the whole thing even less elegant.
39 //
40 // A common way to derive an Id will be to use the entity.DeriveId() function on the serialized operation data.
41 Id() entity.Id
42 // Type return the type of the operation
43 Type() OperationType
44 // Validate check if the Operation data is valid
45 Validate() error
46 // Author returns the author of this operation
47 Author() identity.Interface
48 // Time return the time when the operation was added
49 Time() time.Time
50
51 // SetMetadata store arbitrary metadata about the operation
52 SetMetadata(key string, value string)
53 // GetMetadata retrieve arbitrary metadata about the operation
54 GetMetadata(key string) (string, bool)
55 // AllMetadata return all metadata for this operation
56 AllMetadata() map[string]string
57
58 // setId allow to set the Id, used when unmarshalling only
59 setId(id entity.Id)
60 // setAuthor allow to set the author, used when unmarshalling only
61 setAuthor(author identity.Interface)
62 // setExtraMetadataImmutable add a metadata not carried by the operation itself on the operation
63 setExtraMetadataImmutable(key string, value string)
64}
65
66type OperationWithApply[SnapT Snapshot] interface {
67 Operation
68
69 // Apply the operation to a Snapshot to create the final state
70 Apply(snapshot SnapT)
71}
72
73// OperationWithFiles is an optional extension for an Operation that has files dependency, stored in git.
74type OperationWithFiles interface {
75 // GetFiles return the files needed by this operation
76 // This implies that the Operation maintain and store internally the references to those files. This is how
77 // this information is read later, when loading from storage.
78 // For example, an operation that has a text value referencing some files would maintain a mapping (text ref -->
79 // hash).
80 GetFiles() []repository.Hash
81}
82
83// OperationDoesntChangeSnapshot is an interface signaling that the Operation implementing it doesn't change the
84// snapshot, for example a metadata operation that act on other operations.
85type OperationDoesntChangeSnapshot interface {
86 DoesntChangeSnapshot()
87}
88
89// Snapshot is the minimal interface that a snapshot need to implement
90type Snapshot interface {
91 // AllOperations returns all the operations that have been applied to that snapshot, in order
92 AllOperations() []Operation
93 // AppendOperation add an operation in the list
94 AppendOperation(op Operation)
95}
96
97// OpBase implement the common feature that every Operation should support.
98type OpBase struct {
99 // Not serialized. Store the op's id in memory.
100 id entity.Id
101 // Not serialized
102 author identity.Interface
103
104 OperationType OperationType `json:"type"`
105 UnixTime int64 `json:"timestamp"`
106
107 // mandatory random bytes to ensure a better randomness of the data used to later generate the ID
108 // len(Nonce) should be > 20 and < 64 bytes
109 // It has no functional purpose and should be ignored.
110 Nonce []byte `json:"nonce"`
111
112 Metadata map[string]string `json:"metadata,omitempty"`
113 // Not serialized. Store the extra metadata in memory,
114 // compiled from SetMetadataOperation.
115 extraMetadata map[string]string
116}
117
118func NewOpBase(opType OperationType, author identity.Interface, unixTime int64) OpBase {
119 return OpBase{
120 OperationType: opType,
121 author: author,
122 UnixTime: unixTime,
123 Nonce: makeNonce(20),
124 id: entity.UnsetId,
125 }
126}
127
128func makeNonce(len int) []byte {
129 result := make([]byte, len)
130 _, err := rand.Read(result)
131 if err != nil {
132 panic(err)
133 }
134 return result
135}
136
137func IdOperation(op Operation, base *OpBase) entity.Id {
138 if base.id == "" {
139 // something went really wrong
140 panic("op's id not set")
141 }
142 if base.id == entity.UnsetId {
143 // This means we are trying to get the op's Id *before* it has been stored, for instance when
144 // adding multiple ops in one go in an OperationPack.
145 // As the Id is computed based on the actual bytes written on the disk, we are going to predict
146 // those and then get the Id. This is safe as it will be the exact same code writing on disk later.
147
148 data, err := json.Marshal(op)
149 if err != nil {
150 panic(err)
151 }
152
153 base.id = entity.DeriveId(data)
154 }
155 return base.id
156}
157
158func (base *OpBase) Type() OperationType {
159 return base.OperationType
160}
161
162// Time return the time when the operation was added
163func (base *OpBase) Time() time.Time {
164 return time.Unix(base.UnixTime, 0)
165}
166
167// Validate check the OpBase for errors
168func (base *OpBase) Validate(op Operation, opType OperationType) error {
169 if base.OperationType == 0 {
170 return fmt.Errorf("operation type unset")
171 }
172 if base.OperationType != opType {
173 return fmt.Errorf("incorrect operation type (expected: %v, actual: %v)", opType, base.OperationType)
174 }
175
176 if op.Time().Unix() == 0 {
177 return fmt.Errorf("time not set")
178 }
179
180 if base.author == nil {
181 return fmt.Errorf("author not set")
182 }
183
184 if err := op.Author().Validate(); err != nil {
185 return errors.Wrap(err, "author")
186 }
187
188 if op, ok := op.(OperationWithFiles); ok {
189 for _, hash := range op.GetFiles() {
190 if !hash.IsValid() {
191 return fmt.Errorf("file with invalid hash %v", hash)
192 }
193 }
194 }
195
196 if len(base.Nonce) > 64 {
197 return fmt.Errorf("nonce is too big")
198 }
199 if len(base.Nonce) < 20 {
200 return fmt.Errorf("nonce is too small")
201 }
202
203 return nil
204}
205
206// IsAuthored is a sign post method for gqlgen
207func (base *OpBase) IsAuthored() {}
208
209// Author return author identity
210func (base *OpBase) Author() identity.Interface {
211 return base.author
212}
213
214// IdIsSet returns true if the id has been set already
215func (base *OpBase) IdIsSet() bool {
216 return base.id != "" && base.id != entity.UnsetId
217}
218
219// SetMetadata store arbitrary metadata about the operation
220func (base *OpBase) SetMetadata(key string, value string) {
221 if base.IdIsSet() {
222 panic("set metadata on an operation with already an Id")
223 }
224
225 if base.Metadata == nil {
226 base.Metadata = make(map[string]string)
227 }
228 base.Metadata[key] = value
229}
230
231// GetMetadata retrieve arbitrary metadata about the operation
232func (base *OpBase) GetMetadata(key string) (string, bool) {
233 val, ok := base.Metadata[key]
234
235 if ok {
236 return val, true
237 }
238
239 // extraMetadata can't replace the original operations value if any
240 val, ok = base.extraMetadata[key]
241
242 return val, ok
243}
244
245// AllMetadata return all metadata for this operation
246func (base *OpBase) AllMetadata() map[string]string {
247 result := make(map[string]string)
248
249 for key, val := range base.extraMetadata {
250 result[key] = val
251 }
252
253 // Original metadata take precedence
254 for key, val := range base.Metadata {
255 result[key] = val
256 }
257
258 return result
259}
260
261// setId allow to set the Id, used when unmarshalling only
262func (base *OpBase) setId(id entity.Id) {
263 if base.id != "" && base.id != entity.UnsetId {
264 panic("trying to set id again")
265 }
266 base.id = id
267}
268
269// setAuthor allow to set the author, used when unmarshalling only
270func (base *OpBase) setAuthor(author identity.Interface) {
271 base.author = author
272}
273
274func (base *OpBase) setExtraMetadataImmutable(key string, value string) {
275 if base.extraMetadata == nil {
276 base.extraMetadata = make(map[string]string)
277 }
278 if _, exist := base.extraMetadata[key]; !exist {
279 base.extraMetadata[key] = value
280 }
281}