grove
grove/src/store.rs
at @3
1//! The store: objects, the log, and the state the log adds up to.
2//!
3//! A write is: check the referenced objects exist, apply the record to the in-memory state
4//! (which validates it and changes nothing if it's invalid), then append it to the log. If
5//! the append fails, the state is rebuilt from the log on disk, so memory never claims
6//! something the disk doesn't hold.
7
8use crate::json::{self, Value};
9use crate::log::{Log, OpenError, Recovery};
10use crate::model::{id_to_json, step_to_json, Actor, ChangeState, Project, State, Step};
11use crate::objects::{self, Id, Objects};
12use std::path::{Path, PathBuf};
13use std::time::{SystemTime, UNIX_EPOCH};
14
15#[derive(Debug)]
16pub enum Error {
17 Open(OpenError),
18 Objects(objects::Error),
19 Io(std::io::Error),
20 /// The log holds a record that doesn't fit the state before it.
21 Damaged { record: u64, reason: String },
22 /// The request isn't allowed or doesn't make sense.
23 Refused(String),
24 /// Landing needs the change rebuilt on the current tip first.
25 Behind { base: u64, tip: u64 },
26}
27
28impl std::fmt::Display for Error {
29 fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
30 match self {
31 Error::Open(e) => write!(f, "{e}"),
32 Error::Objects(e) => write!(f, "{e}"),
33 Error::Io(e) => write!(f, "{e}"),
34 Error::Damaged { record, reason } => write!(f, "log record {record} is damaged: {reason}"),
35 Error::Refused(r) => write!(f, "{r}"),
36 Error::Behind { base, tip } => write!(f, "built on point {base}, but main is at {tip}; rebuild on the tip first"),
37 }
38 }
39}
40
41impl From<OpenError> for Error {
42 fn from(e: OpenError) -> Self {
43 Error::Open(e)
44 }
45}
46impl From<objects::Error> for Error {
47 fn from(e: objects::Error) -> Self {
48 Error::Objects(e)
49 }
50}
51impl From<std::io::Error> for Error {
52 fn from(e: std::io::Error) -> Self {
53 Error::Io(e)
54 }
55}
56
57pub type Result<T> = std::result::Result<T, Error>;
58
59fn refused<T>(msg: impl Into<String>) -> Result<T> {
60 Err(Error::Refused(msg.into()))
61}
62
63/// What a piece of evidence holds.
64pub enum Content<'a> {
65 Bytes(&'a [u8]),
66 Url(&'a str),
67}
68
69pub fn now_ms() -> i64 {
70 SystemTime::now().duration_since(UNIX_EPOCH).map(|d| d.as_millis() as i64).unwrap_or(0)
71}
72
73pub struct Store {
74 dir: PathBuf,
75 log: Log,
76 pub objects: Objects,
77 state: State,
78 pub recovery: Recovery,
79}
80
81fn replay(records: &[Vec<u8>]) -> Result<State> {
82 let mut state = State::default();
83 for (i, bytes) in records.iter().enumerate() {
84 let damaged = |reason: String| Error::Damaged { record: i as u64, reason };
85 let text = std::str::from_utf8(bytes).map_err(|_| damaged("not UTF-8".into()))?;
86 let rec = json::parse(text).map_err(|e| damaged(e.to_string()))?;
87 state.apply(&rec).map_err(damaged)?;
88 }
89 Ok(state)
90}
91
92impl Store {
93 pub fn open(dir: &Path) -> Result<Store> {
94 std::fs::create_dir_all(dir)?;
95 let objects = Objects::open(&dir.join("objects"))?;
96 let (log, records, recovery) = Log::open(&dir.join("log"))?;
97 let state = replay(&records)?;
98 Ok(Store { dir: dir.to_path_buf(), log, objects, state, recovery })
99 }
100
101 pub fn dir(&self) -> &Path {
102 &self.dir
103 }
104
105 pub fn state(&self) -> &State {
106 &self.state
107 }
108
109 /// Validate, apply, append. `rec` gets its time and actor here.
110 fn write(&mut self, by: &Actor, mut rec: Vec<(String, Value)>) -> Result<()> {
111 rec.insert(1, ("at".into(), now_ms().into()));
112 rec.insert(2, ("by".into(), by.to_json()));
113 let rec = Value::Object(rec);
114 self.state.apply(&rec).map_err(Error::Refused)?;
115 if let Err(e) = self.log.append(rec.encode().as_bytes()) {
116 // The state now holds a record the log doesn't. Rebuild it from the disk.
117 let (log, records, _) = Log::open(&self.dir.join("log")).map_err(|_| Error::Io(e))?;
118 self.log = log;
119 self.state = replay(&records)?;
120 return Err(Error::Refused("couldn't write to the log".into()));
121 }
122 Ok(())
123 }
124
125 fn rec(t: &str, fields: Vec<(&str, Value)>) -> Vec<(String, Value)> {
126 let mut out = vec![("t".to_string(), Value::from(t))];
127 out.extend(fields.into_iter().map(|(k, v)| (k.to_string(), v)));
128 out
129 }
130
131 fn require_tree(&self, id: &Id) -> Result<()> {
132 if !self.objects.has(id) {
133 return refused(format!("snapshot {} isn't stored", crate::hex::encode(id)));
134 }
135 Ok(())
136 }
137
138 pub fn project(&self, owner: &str, name: &str) -> Result<&Project> {
139 self.state.project(owner, name).ok_or_else(|| Error::Refused(format!("no project {owner}/{name}")))
140 }
141
142 // ── People and agents ──────────────────────────────────
143
144 pub fn add_person(&mut self, username: &str, display_name: &str) -> Result<()> {
145 if !username.chars().all(|c| c.is_ascii_alphanumeric() || c == '-' || c == '_') || username.is_empty() {
146 return refused("usernames are letters, digits, - and _");
147 }
148 self.write(&Actor::person(username), Self::rec("person", vec![("username", username.into()), ("display_name", display_name.into())]))
149 }
150
151 /// Register an agent acting for `person`. Returns its id.
152 pub fn add_agent(&mut self, person: &str, name: &str) -> Result<String> {
153 let id = crate::random::hex(6);
154 self.write(&Actor::person(person), Self::rec("agent", vec![("id", id.clone().into()), ("name", name.into())]))?;
155 Ok(id)
156 }
157
158 pub fn revoke_agent(&mut self, person: &str, id: &str) -> Result<()> {
159 self.write(&Actor::person(person), Self::rec("agent.revoke", vec![("id", id.into())]))
160 }
161
162 // ── Projects and main ──────────────────────────────────
163
164 /// Create a project owned by `owner`: the actor themselves or a group they're in.
165 pub fn create_project(&mut self, by: &Actor, owner: &str, name: &str, public: bool) -> Result<()> {
166 if !objects::valid_name(name) || name.contains(char::is_whitespace) {
167 return refused(format!("{name:?} can't be a project name"));
168 }
169 self.write(by, Self::rec("project", vec![("owner", owner.into()), ("name", name.into()), ("public", public.into())]))
170 }
171
172 /// Give a project to another owner. History goes with it.
173 pub fn move_project(&mut self, by: &Actor, owner: &str, name: &str, to: &str) -> Result<()> {
174 self.write(by, Self::rec("project.move", vec![("owner", owner.into()), ("project", name.into()), ("to", to.into())]))
175 }
176
177 pub fn create_group(&mut self, by: &Actor, name: &str) -> Result<()> {
178 if !name.chars().all(|c| c.is_ascii_alphanumeric() || c == '-' || c == '_') || name.is_empty() {
179 return refused("group names are letters, digits, - and _");
180 }
181 self.write(by, Self::rec("group", vec![("name", name.into())]))
182 }
183
184 pub fn add_member(&mut self, by: &Actor, group: &str, person: &str) -> Result<()> {
185 self.write(by, Self::rec("group.add", vec![("group", group.into()), ("person", person.into())]))
186 }
187
188 /// Record a point directly on main: a project's first snapshot, or imported history.
189 pub fn record_point(&mut self, by: &Actor, owner: &str, name: &str, snapshot: &Id, message: &str, author: Option<&Actor>) -> Result<u64> {
190 self.require_tree(snapshot)?;
191 let n = self.project(owner, name)?.tip() + 1;
192 let mut fields = vec![
193 ("owner", owner.into()),
194 ("project", name.into()),
195 ("n", n.into()),
196 ("snapshot", id_to_json(snapshot)),
197 ("message", message.into()),
198 ];
199 if let Some(a) = author {
200 fields.push(("author", a.to_json()));
201 }
202 self.write(by, Self::rec("point", fields))?;
203 Ok(n)
204 }
205
206 // ── Changes ────────────────────────────────────────────
207
208 /// Open a change as an idea: an intent, no code yet. Its first revision makes it a draft.
209 pub fn open_change(&mut self, by: &Actor, owner: &str, name: &str, intent: &str) -> Result<u64> {
210 let p = self.project(owner, name)?;
211 if !p.public && !self.state.owns(&p.owner, &by.person) {
212 return refused(format!("{owner}/{name} is private"));
213 }
214 let number = p.changes.len() as u64 + 1;
215 self.write(by, Self::rec("change", vec![("owner", owner.into()), ("project", name.into()), ("number", number.into()), ("intent", intent.into()), ("state", "idea".into())]))?;
216 Ok(number)
217 }
218
219 /// Add a revision: the whole stack of steps, built on main point `base`.
220 pub fn revise(&mut self, by: &Actor, owner: &str, name: &str, change: u64, base: u64, steps: &[Step], note: Option<&str>) -> Result<u32> {
221 for s in steps {
222 self.require_tree(&s.snapshot)?;
223 }
224 let p = self.project(owner, name)?;
225 let c = p.change(change).ok_or_else(|| Error::Refused(format!("no change #{change}")))?;
226 if by.person != c.proposer.person && !self.state.owns(&p.owner, &by.person) {
227 return refused("only the proposer or the owner can revise a change");
228 }
229 let number = c.revisions.len() as u32 + 1;
230 let steps: Vec<Value> = steps.iter().map(step_to_json).collect();
231 self.write(
232 by,
233 Self::rec("revision", vec![
234 ("owner", owner.into()),
235 ("project", name.into()),
236 ("change", change.into()),
237 ("number", (number as u64).into()),
238 ("base", base.into()),
239 ("steps", steps.into()),
240 ("note", note.map(str::to_string).into()),
241 ]),
242 )?;
243 Ok(number)
244 }
245
246 pub fn set_state(&mut self, by: &Actor, owner: &str, name: &str, change: u64, to: ChangeState) -> Result<()> {
247 if to == ChangeState::Landed {
248 return refused("changes land through land()");
249 }
250 self.write(by, Self::rec("state", vec![("owner", owner.into()), ("project", name.into()), ("change", change.into()), ("state", to.name().into())]))
251 }
252
253 /// Land a change's latest revision. Its steps become the next points on main, all at once.
254 pub fn land(&mut self, by: &Actor, owner: &str, name: &str, change: u64) -> Result<(u64, u64)> {
255 let p = self.project(owner, name)?;
256 if !self.state.owns(&p.owner, &by.person) || by.agent.is_some() {
257 return refused("only the owner, in person, lands changes");
258 }
259 let c = p.change(change).ok_or_else(|| Error::Refused(format!("no change #{change}")))?;
260 let rev = c.latest().ok_or_else(|| Error::Refused(format!("#{change} has no revisions")))?;
261 if rev.base != p.tip() {
262 return Err(Error::Behind { base: rev.base, tip: p.tip() });
263 }
264 let first = p.tip() + 1;
265 let count = rev.steps.len() as u64;
266 let snapshots: Vec<Value> = rev.steps.iter().map(|s| id_to_json(&s.snapshot)).collect();
267 let revision = rev.number as u64;
268 self.write(
269 by,
270 Self::rec("land", vec![
271 ("owner", owner.into()),
272 ("project", name.into()),
273 ("change", change.into()),
274 ("revision", revision.into()),
275 ("first", first.into()),
276 ("snapshots", snapshots.into()),
277 ]),
278 )?;
279 Ok((first, first + count - 1))
280 }
281
282 pub fn say(&mut self, by: &Actor, owner: &str, name: &str, change: u64, body: &str) -> Result<()> {
283 self.write(by, Self::rec("say", vec![("owner", owner.into()), ("project", name.into()), ("change", change.into()), ("body", body.into())]))
284 }
285
286 /// Attach evidence to a revision: stored bytes of a media type, or a URL.
287 pub fn attach(&mut self, by: &Actor, owner: &str, name: &str, change: u64, revision: u32, title: &str, media_type: &str, content: Content) -> Result<()> {
288 let (blob, url) = match content {
289 Content::Bytes(bytes) => (Value::from(crate::hex::encode(&self.objects.put_blob(bytes)?)), Value::Null),
290 Content::Url(url) => (Value::Null, Value::from(url)),
291 };
292 self.write(
293 by,
294 Self::rec("evidence", vec![
295 ("owner", owner.into()),
296 ("project", name.into()),
297 ("change", change.into()),
298 ("revision", (revision as u64).into()),
299 ("title", title.into()),
300 ("type", media_type.into()),
301 ("blob", blob),
302 ("url", url),
303 ]),
304 )
305 }
306
307 /// Check that every object the state refers to exists and matches its id.
308 pub fn verify(&self) -> Result<usize> {
309 let mut count = 0;
310 let mut seen = std::collections::HashSet::new();
311 let mut check_tree = |id: &Id, count: &mut usize| -> Result<()> {
312 if seen.insert(*id) {
313 *count += self.objects.verify_tree(id)?;
314 }
315 Ok(())
316 };
317 for p in &self.state.projects {
318 for pt in &p.points {
319 check_tree(&pt.snapshot, &mut count)?;
320 }
321 for c in &p.changes {
322 for r in &c.revisions {
323 for s in &r.steps {
324 check_tree(&s.snapshot, &mut count)?;
325 }
326 }
327 for e in &c.evidence {
328 if let Some(b) = &e.blob {
329 self.objects.get_blob(b)?;
330 count += 1;
331 }
332 }
333 }
334 }
335 Ok(count)
336 }
337}
338
339#[cfg(test)]
340mod tests {
341 use super::*;
342 use crate::objects::{Entry, Kind};
343 use crate::testdir::TestDir;
344
345 fn tree(store: &Store, files: &[(&str, &str)]) -> Id {
346 let entries: Vec<Entry> = files
347 .iter()
348 .map(|(n, c)| Entry { name: n.to_string(), kind: Kind::File, id: store.objects.put_blob(c.as_bytes()).unwrap() })
349 .collect();
350 store.objects.put_tree(&entries).unwrap()
351 }
352
353 fn setup(dir: &TestDir) -> (Store, Actor, String) {
354 let mut store = Store::open(dir.path()).unwrap();
355 store.add_person("anton", "Anton").unwrap();
356 let agent = store.add_agent("anton", "claude").unwrap();
357 let me = Actor::agent("anton", &agent);
358 store.create_project(&Actor::person("anton"), "anton", "grove", true).unwrap();
359 let t = tree(&store, &[("README", "hello")]);
360 store.record_point(&Actor::person("anton"), "anton", "grove", &t, "Start", None).unwrap();
361 (store, me, agent)
362 }
363
364 #[test]
365 fn change_lifecycle_and_replay() {
366 let dir = TestDir::new("store-lifecycle");
367 {
368 let (mut store, me, _) = setup(&dir);
369 let owner = Actor::person("anton");
370 let c = store.open_change(&me, "anton", "grove", "Say more in the README").unwrap();
371 assert_eq!(store.project("anton", "grove").unwrap().change(c).unwrap().state, ChangeState::Idea);
372
373 let t1 = tree(&store, &[("README", "hello there")]);
374 let t2 = tree(&store, &[("README", "hello there"), ("NOTES", "x")]);
375 let steps = vec![
376 Step { id: "s1".into(), snapshot: t1, message: "Longer greeting".into() },
377 Step { id: "s2".into(), snapshot: t2, message: "Add notes".into() },
378 ];
379 assert_eq!(store.revise(&me, "anton", "grove", c, 1, &steps, None).unwrap(), 1);
380 store.set_state(&me, "anton", "grove", c, ChangeState::Proposed).unwrap();
381 store.say(&owner, "anton", "grove", c, "Looks good").unwrap();
382 store.attach(&me, "anton", "grove", c, 1, "notes", "text/plain", Content::Bytes(b"checked by hand")).unwrap();
383
384 // Only the owner lands.
385 assert!(matches!(store.land(&me, "anton", "grove", c), Err(Error::Refused(_))));
386 assert_eq!(store.land(&owner, "anton", "grove", c).unwrap(), (2, 3));
387 let p = store.project("anton", "grove").unwrap();
388 assert_eq!(p.tip(), 3);
389 assert_eq!(p.point(3).unwrap().snapshot, t2);
390 assert_eq!(p.change(c).unwrap().state, ChangeState::Landed);
391 assert_eq!(store.verify().unwrap() > 0, true);
392 }
393 // Everything comes back from the log.
394 let store = Store::open(dir.path()).unwrap();
395 let p = store.project("anton", "grove").unwrap();
396 assert_eq!(p.tip(), 3);
397 let c = p.change(1).unwrap();
398 assert_eq!(c.state, ChangeState::Landed);
399 assert_eq!(c.messages[0].body, "Looks good");
400 assert_eq!(c.evidence.len(), 1);
401 assert_eq!(p.point(2).unwrap().message, "Longer greeting");
402 assert!(p.point(2).unwrap().author.agent.is_some());
403 }
404
405 #[test]
406 fn landing_behind_the_tip_is_refused() {
407 let dir = TestDir::new("store-behind");
408 let (mut store, me, _) = setup(&dir);
409 let owner = Actor::person("anton");
410 let t = tree(&store, &[("README", "a")]);
411 let step = |id: &str| vec![Step { id: id.into(), snapshot: t, message: "m".into() }];
412 let a = store.open_change(&me, "anton", "grove", "a").unwrap();
413 let b = store.open_change(&me, "anton", "grove", "b").unwrap();
414 store.revise(&me, "anton", "grove", a, 1, &step("x"), None).unwrap();
415 store.revise(&me, "anton", "grove", b, 1, &step("y"), None).unwrap();
416 store.set_state(&me, "anton", "grove", a, ChangeState::Proposed).unwrap();
417 store.set_state(&me, "anton", "grove", b, ChangeState::Proposed).unwrap();
418 store.land(&owner, "anton", "grove", a).unwrap();
419 assert!(matches!(store.land(&owner, "anton", "grove", b), Err(Error::Behind { base: 1, tip: 2 })));
420 // Nothing changed for b.
421 assert_eq!(store.project("anton", "grove").unwrap().change(b).unwrap().state, ChangeState::Proposed);
422 }
423
424 #[test]
425 fn refusals_leave_no_trace() {
426 let dir = TestDir::new("store-refusals");
427 let (mut store, me, agent) = setup(&dir);
428 let before = store.state().records;
429 // Unstored snapshot, unknown project, bad transition, revoked agent.
430 let ghost = crate::objects::blob_id(b"not stored");
431 assert!(store.record_point(&Actor::person("anton"), "anton", "grove", &ghost, "x", None).is_err());
432 assert!(store.open_change(&me, "anton", "nope", "x").is_err());
433 let c = store.open_change(&me, "anton", "grove", "idea").unwrap();
434 assert!(store.set_state(&me, "anton", "grove", c, ChangeState::Proposed).is_err(), "an idea can't be proposed");
435 store.revoke_agent("anton", &agent).unwrap();
436 assert!(store.say(&me, "anton", "grove", c, "still here?").is_err());
437 assert_eq!(store.state().records, before + 2, "only the change and the revocation were written");
438 drop(store);
439 assert_eq!(Store::open(dir.path()).unwrap().state().records, before + 2);
440 }
441
442 #[test]
443 fn groups_own_projects() {
444 let dir = TestDir::new("store-groups");
445 let (mut store, me, _) = setup(&dir);
446 let anton = Actor::person("anton");
447 store.add_person("bea", "Bea").unwrap();
448 let bea = Actor::person("bea");
449 assert!(store.create_group(&me, "letterpress").is_err(), "groups are created in person");
450 store.create_group(&anton, "letterpress").unwrap();
451 assert!(store.create_group(&anton, "bea").is_err(), "names are shared with people");
452 // Move grove to the group; its history goes with it.
453 assert!(store.move_project(&bea, "anton", "grove", "letterpress").is_err());
454 store.move_project(&anton, "anton", "grove", "letterpress").unwrap();
455 assert!(store.project("anton", "grove").is_err());
456 assert_eq!(store.project("letterpress", "grove").unwrap().tip(), 1);
457 // Members decide for the group; others don't.
458 let t = tree(&store, &[("README", "group")]);
459 let c = store.open_change(&bea, "letterpress", "grove", "from bea").unwrap();
460 store.revise(&bea, "letterpress", "grove", c, 1, &[Step { id: "s".into(), snapshot: t, message: "m".into() }], None).unwrap();
461 store.set_state(&bea, "letterpress", "grove", c, ChangeState::Proposed).unwrap();
462 assert!(store.land(&bea, "letterpress", "grove", c).is_err());
463 store.add_member(&anton, "letterpress", "bea").unwrap();
464 store.land(&bea, "letterpress", "grove", c).unwrap();
465 drop(store);
466 let store = Store::open(dir.path()).unwrap();
467 assert_eq!(store.project("letterpress", "grove").unwrap().tip(), 2);
468 assert_eq!(store.state().group("letterpress").unwrap().members, ["anton", "bea"]);
469 }
470
471 #[test]
472 fn strangers_and_private_projects() {
473 let dir = TestDir::new("store-strangers");
474 let (mut store, _, _) = setup(&dir);
475 store.add_person("visitor", "Visitor").unwrap();
476 let visitor = Actor::person("visitor");
477 // Anyone can propose to a public project, but not land.
478 let c = store.open_change(&visitor, "anton", "grove", "An idea from outside").unwrap();
479 let t = tree(&store, &[("README", "outside")]);
480 store.revise(&visitor, "anton", "grove", c, 1, &[Step { id: "s".into(), snapshot: t, message: "m".into() }], None).unwrap();
481 store.set_state(&visitor, "anton", "grove", c, ChangeState::Proposed).unwrap();
482 assert!(store.land(&visitor, "anton", "grove", c).is_err());
483 store.set_state(&Actor::person("anton"), "anton", "grove", c, ChangeState::Declined).unwrap();
484 // Private projects take changes only from the owner.
485 store.create_project(&Actor::person("anton"), "anton", "secret", false).unwrap();
486 assert!(store.open_change(&visitor, "anton", "secret", "let me in").is_err());
487 }
488}