menger_notes/activation.rs
1//! The `notes` activation — **the one declaration**, as `tickets`, `ui` and
2//! `media` are: the `Activation` impl, dispatch, the schema and the
3//! methods' bodies from this `impl`, and `NotesClient<T>` for a client of it
4//! (the media service's `notes.may`, a test).
5//!
6//! **Under login**: a viewer reads (`get`, `list`, `state`, `history`,
7//! `replay`, `present`, `watch`, `may`, `threads`, `waiting`, `marks`) and is present
8//! (`here`), an editor writes (`create`, `update`, `save`, `rename`,
9//! `restore`), asks and answers on a range (`ask`, `reply`, `resolve`) and
10//! marks one (`mark`, `unmark`: NOTES-5, never writing the text), an admin
11//! deletes and squashes (`delete`, `squash`: unlisted — admin holds every
12//! grant; `notes.squash` is grantable to another role by the role table). The gate
13//! admits a call when its grant is held somewhere; the method asks it again
14//! on the note's organization (`acme:`) through the seam — a note
15//! in an organization the caller does not read is `not_found`, one it
16//! reads and may not write `refused { forbidden }`.
17//!
18//! NOTES-4: a note's slot — `slot` a viewer's; `fill`, `empty`,
19//! `building` and `props` an editor's of the note ([`crate::slot`]).
20
21use crate::caller::{Caller, Callers, NotesRequest};
22use crate::events::NotesEvent;
23use crate::seam::Seam;
24use crate::store::NotesStore;
25use crate::streams::{many, once};
26use crate::vocab::{AgentName, BuildStep, ComponentName, SlotProps, SlotSay, VersionRef, ThreadId, ThreadText, NoteAwareness, NoteBody, NoteId, NoteQuery, NoteSession, NoteTitle, NoteUpdate, NoteVector, MarkId, MarkLabel, MarkLink};
27use futures::Stream;
28use menger_tickets_api::address::OrgId;
29use menger_tickets_api::members::Role;
30use std::sync::Arc;
31
32/// The activation: the store over `notes.db`, the seam to the running
33/// service, and the resolver every caller is verified by.
34#[derive(Clone)]
35pub struct NotesActivation {
36 store: Arc<NotesStore>,
37 seam: Seam,
38 callers: Callers,
39}
40
41impl NotesActivation {
42 /// Over `store`. Inside a runtime, presence that idled out is swept
43 /// every few seconds for as long as the store lives (and said `left`).
44 pub fn new(store: Arc<NotesStore>) -> Self {
45 if let Ok(rt) = tokio::runtime::Handle::try_current() {
46 let weak = Arc::downgrade(&store);
47 rt.spawn(async move {
48 let mut every = tokio::time::interval(std::time::Duration::from_secs(5));
49 loop {
50 every.tick().await;
51 match weak.upgrade() {
52 Some(store) => {
53 store.sweep();
54 store.sweep_builds();
55 }
56 None => return,
57 }
58 }
59 });
60 }
61 Self { store, seam: Seam::default(), callers: Callers }
62 }
63
64 /// The seam the builder attaches its running service to, once built.
65 pub fn seam(&self) -> &Seam {
66 &self.seam
67 }
68
69 /// The store it keeps.
70 pub fn store(&self) -> &Arc<NotesStore> {
71 &self.store
72 }
73}
74
75/// Notes: writing on its own, written by many hands at once — make one, read it, write it live (a Yjs CRDT), see who is on it, replay how it was built.
76#[plexus_rpc::macros::activation(
77 auth = "required",
78 request = NotesRequest,
79 typed_params,
80 roles(
81 viewer = ["get", "list", "state", "history", "replay", "present", "here", "watch", "may", "threads", "waiting", "slot", "marks"],
82 editor = [viewer, "create", "update", "save", "rename", "restore", "ask", "reply", "resolve", "fill", "empty", "building", "props", "mark", "unmark", "mark_props"],
83 )
84)]
85impl NotesActivation {
86 /// Make a note in an organization you write in; yields created { note } (revision 1, its id 8 characters, opened at #/note/<id>).
87 ///
88 /// `org` names the organization (`acme`); without it, the first one you
89 /// write notes in. Who may read and write the note is the roles
90 /// held on its organization (`acme:`) or on `*`. Refused in band:
91 /// `not_found { org }` for an organization you are not in, `refused {
92 /// forbidden }` for one you only read. Editor.
93 #[plexus_rpc::macros::method(
94 group = "write",
95 example(note = "a note, titled", params = r#"{"title": "The kiln, in practice", "body": "Fire twice a week."}"#)
96 )]
97 pub async fn create(
98 &self,
99 #[from_auth(self.callers.verify)] user: Caller,
100 /// Its title, one line, e.g. The kiln, in practice.
101 title: NoteTitle,
102 /// Its markdown (optional: empty).
103 body: Option<NoteBody>,
104 /// The organization it is in, e.g. acme (optional: the first you write notes in).
105 org: Option<OrgId>,
106 ) -> impl Stream<Item = NotesEvent> + Send + 'static {
107 let (store, seam) = (self.store.clone(), self.seam.clone());
108 once(crate::streams::create(store, seam, user, title.into_string(), body.map(NoteBody::into_string).unwrap_or_default(), org.map(|o| o.as_str().to_string())))
109 }
110
111 /// A note whole; yields note { note } — its title, its body (the markdown its CRDT holds now), its revision, who made it and who wrote it last — or not_found.
112 ///
113 /// A note in an organization you do not read is `not_found`, as one
114 /// there is not. `replay` reads it as it stood at a moment. Viewer.
115 #[plexus_rpc::macros::method(group = "read", example(note = "a note by its id", params = r#"{"id": "7k3mq2xa"}"#))]
116 pub async fn get(
117 &self,
118 #[from_auth(self.callers.verify)] user: Caller,
119 /// Its id, e.g. 7k3mq2xa.
120 id: NoteId,
121 ) -> impl Stream<Item = NotesEvent> + Send + 'static {
122 let (store, seam) = (self.store.clone(), self.seam.clone());
123 once(crate::streams::get(store, seam, user, id.into_string()))
124 }
125
126 /// The notes you read, newest made first, without their bodies; yields rows { items: [note { note }] } then page { next, remaining }.
127 ///
128 /// `query` keeps those whose title holds every word of it, case-blind.
129 /// A page is 50 rows unless `limit` says (at most 1,000); `after` is the
130 /// last row's id of the page before (`page.next`). Viewer.
131 #[plexus_rpc::macros::method(group = "read", example(note = "the notes about the kiln", params = r#"{"query": "kiln", "limit": 20}"#))]
132 pub async fn list(
133 &self,
134 #[from_auth(self.callers.verify)] user: Caller,
135 /// Words the title holds, e.g. kiln glaze (optional: every note).
136 query: Option<NoteQuery>,
137 /// The page's size, e.g. 50 (optional: 50; at most 1000).
138 limit: Option<u32>,
139 /// The id the page before ended at, as its page.next said (optional: the first page).
140 after: Option<NoteId>,
141 ) -> impl Stream<Item = NotesEvent> + Send + 'static {
142 let (store, seam) = (self.store.clone(), self.seam.clone());
143 many(crate::streams::list(store, seam, user, query.map(NoteQuery::into_string).filter(|q| !q.is_empty()), limit, after.map(NoteId::into_string)))
144 }
145
146 /// Write a note's body whole — merged with whatever else is being written; yields saved { id, revision, at, by } (stale: true when base was not the revision it found).
147 ///
148 /// For an agent or a script over synapse: the body given is diffed
149 /// against the text now and made into the CRDT's own inserts and deletes,
150 /// so it merges with live typing instead of overwriting it (a hand typing
151 /// in a paragraph the body did not change keeps its words). `base` is the
152 /// revision you read (`note.revision`). A body equal to the text writes
153 /// nothing. The editor sends `update`s instead. Editor.
154 #[plexus_rpc::macros::method(group = "write", example(note = "a body, read at revision 3", params = r##"{"id": "7k3mq2xa", "body": "# The kiln\n\nFire twice a week.\n", "base": 3}"##))]
155 pub async fn save(
156 &self,
157 #[from_auth(self.callers.verify)] user: Caller,
158 /// Its id, e.g. 7k3mq2xa.
159 id: NoteId,
160 /// The markdown, whole.
161 body: NoteBody,
162 /// The revision you read, e.g. 3 (optional: none said, never stale).
163 base: Option<u32>,
164 ) -> impl Stream<Item = NotesEvent> + Send + 'static {
165 let (store, seam) = (self.store.clone(), self.seam.clone());
166 once(crate::streams::save(store, seam, user, id.into_string(), body.into_string(), base))
167 }
168
169 /// Apply a Yjs update to a note's body — the editor's live typing; yields applied { id, revision }.
170 ///
171 /// `update` is a Yjs v1 update of the note's `body` text (base64),
172 /// as the page's `ydoc` made it; it is merged into the note's CRDT,
173 /// kept as a change with you and the moment, and said to everyone on the
174 /// note (`watch`'s `updated`) — not back to `session`, when you name
175 /// the presence it came from. Editor.
176 #[plexus_rpc::macros::method(group = "write")]
177 pub async fn update(
178 &self,
179 #[from_auth(self.callers.verify)] user: Caller,
180 /// Its id, e.g. 7k3mq2xa.
181 id: NoteId,
182 /// The Yjs v1 update, base64.
183 update: NoteUpdate,
184 /// Your page's session on it, as your watch named it (optional).
185 session: Option<NoteSession>,
186 ) -> impl Stream<Item = NotesEvent> + Send + 'static {
187 let (store, seam) = (self.store.clone(), self.seam.clone());
188 once(crate::streams::update(store, seam, user, id.into_string(), update.into_string(), session.map(NoteSession::into_string)))
189 }
190
191 /// What your copy of a note's CRDT lacks; yields state { id, update, vector, revision } — the Yjs update to apply, and the note's own state vector.
192 ///
193 /// `vector` is your state vector (`Y.encodeStateVector`, base64); with
194 /// none, the whole note. Send back what the note lacks of yours
195 /// (`Y.encodeStateAsUpdate(ydoc, vector)`) as an `update`. Viewer.
196 #[plexus_rpc::macros::method(group = "read", example(note = "the whole note", params = r#"{"id": "7k3mq2xa"}"#))]
197 pub async fn state(
198 &self,
199 #[from_auth(self.callers.verify)] user: Caller,
200 /// Its id, e.g. 7k3mq2xa.
201 id: NoteId,
202 /// Your state vector, base64 (optional: you hold nothing).
203 vector: Option<NoteVector>,
204 ) -> impl Stream<Item = NotesEvent> + Send + 'static {
205 let (store, seam) = (self.store.clone(), self.seam.clone());
206 once(crate::streams::state(store, seam, user, id.into_string(), vector.map(NoteVector::into_string)))
207 }
208
209 /// Every change of a note, newest first; yields change { change: { seq, kind, at, by, principal, bytes, title?, authors? } } each.
210 ///
211 /// Every change is kept with who and when until squashed: `create`,
212 /// `update` (live typing), `save` (a whole body, merged), `rename`,
213 /// `delete`, and `snapshot` (a squash: its `authors` say who wrote what
214 /// in it). `at` is unix milliseconds. `before` pages back by `seq`. Viewer.
215 #[plexus_rpc::macros::method(group = "read", example(note = "the last twenty", params = r#"{"id": "7k3mq2xa", "limit": 20}"#))]
216 pub async fn history(
217 &self,
218 #[from_auth(self.callers.verify)] user: Caller,
219 /// Its id, e.g. 7k3mq2xa.
220 id: NoteId,
221 /// How many, e.g. 20 (optional: up to 1000).
222 limit: Option<u32>,
223 /// Only changes before this seq, e.g. 120 (optional: from the newest).
224 before: Option<u32>,
225 ) -> impl Stream<Item = NotesEvent> + Send + 'static {
226 let (store, seam) = (self.store.clone(), self.seam.clone());
227 many(crate::streams::history(store, seam, user, id.into_string(), limit, before))
228 }
229
230 /// A note as it stood at a moment; yields note { note } — its title and body then, revision the change it stood at — or not_found { revision }.
231 ///
232 /// `seq` stands it after that change (`history`'s); `at` (unix
233 /// milliseconds) after the last change made by then. A moment before the
234 /// first change kept — squashed away — is `not_found`. With neither, now.
235 /// Viewer.
236 #[plexus_rpc::macros::method(group = "read", example(note = "after its tenth change", params = r#"{"id": "7k3mq2xa", "seq": 10}"#))]
237 pub async fn replay(
238 &self,
239 #[from_auth(self.callers.verify)] user: Caller,
240 /// Its id, e.g. 7k3mq2xa.
241 id: NoteId,
242 /// After this change, e.g. 10 (optional).
243 seq: Option<u32>,
244 /// At this moment, unix milliseconds, e.g. 1793608333000 (optional).
245 at: Option<i64>,
246 ) -> impl Stream<Item = NotesEvent> + Send + 'static {
247 let (store, seam) = (self.store.clone(), self.seam.clone());
248 once(crate::streams::replay(store, seam, user, id.into_string(), seq, at))
249 }
250
251 /// Collapse a note's changes up to a moment into one snapshot, keeping who wrote what; yields squashed { id, until, removed, at, by }, said on watch.
252 ///
253 /// The changes up to `until` (a `seq`) become one `snapshot` change whose
254 /// `authors` say each writer's changes and bytes; later changes stay as
255 /// they are. A replay before `until` is `not_found` after. Needs its own
256 /// grant, `notes.squash`, on the note's organization — admin's by
257 /// default, grantable to a role by the role table; refused typed
258 /// without it. Admin.
259 #[plexus_rpc::macros::method(group = "admin", example(note = "everything before change 200", params = r#"{"id": "7k3mq2xa", "until": 200}"#))]
260 pub async fn squash(
261 &self,
262 #[from_auth(self.callers.verify)] user: Caller,
263 /// Its id, e.g. 7k3mq2xa.
264 id: NoteId,
265 /// The last change to fold in, e.g. 200.
266 until: u32,
267 ) -> impl Stream<Item = NotesEvent> + Send + 'static {
268 let (store, seam) = (self.store.clone(), self.seam.clone());
269 once(crate::streams::squash(store, seam, user, id.into_string(), until))
270 }
271
272 /// Who is on a note now; yields present { present: { session, principal, name, agent, colour, client?, awareness?, at } } each.
273 ///
274 /// A connection is on it while its `watch { id, session }` is open; a
275 /// writer without one (an agent's `save`) while it writes, idling out
276 /// after 30 s. Viewer.
277 #[plexus_rpc::macros::method(group = "read", example(note = "who is here", params = r#"{"id": "7k3mq2xa"}"#))]
278 pub async fn present(
279 &self,
280 #[from_auth(self.callers.verify)] user: Caller,
281 /// Its id, e.g. 7k3mq2xa.
282 id: NoteId,
283 ) -> impl Stream<Item = NotesEvent> + Send + 'static {
284 let (store, seam) = (self.store.clone(), self.seam.clone());
285 many(crate::streams::present(store, seam, user, id.into_string()))
286 }
287
288 /// Say where your caret is on a note; yields present { present }, said to everyone on it.
289 ///
290 /// `awareness` is your page's Yjs awareness update (base64) — your
291 /// caret, your selection — and `client` your Yjs client id; `session`
292 /// your page's, as your watch named it (one someone else holds is
293 /// refused). Viewer.
294 #[plexus_rpc::macros::method(group = "read")]
295 pub async fn here(
296 &self,
297 #[from_auth(self.callers.verify)] user: Caller,
298 /// Its id, e.g. 7k3mq2xa.
299 id: NoteId,
300 /// Your page's session on it, e.g. s-3f9a1c.
301 session: NoteSession,
302 /// Your Yjs client id (optional).
303 client: Option<u64>,
304 /// Your Yjs awareness update, base64 (optional).
305 awareness: Option<NoteAwareness>,
306 ) -> impl Stream<Item = NotesEvent> + Send + 'static {
307 let (store, seam) = (self.store.clone(), self.seam.clone());
308 once(crate::streams::here(store, seam, user, id.into_string(), session.into_string(), client, awareness.map(NoteAwareness::into_string)))
309 }
310
311 /// Retitle a note; yields renamed { id, title, revision, at, by }. Editor.
312 #[plexus_rpc::macros::method(group = "write", example(note = "a new title", params = r#"{"id": "7k3mq2xa", "title": "The kiln, weekly"}"#))]
313 pub async fn rename(
314 &self,
315 #[from_auth(self.callers.verify)] user: Caller,
316 /// Its id, e.g. 7k3mq2xa.
317 id: NoteId,
318 /// The new title, one line.
319 title: NoteTitle,
320 ) -> impl Stream<Item = NotesEvent> + Send + 'static {
321 let (store, seam) = (self.store.clone(), self.seam.clone());
322 once(crate::streams::rename(store, seam, user, id.into_string(), title.into_string()))
323 }
324
325 /// Delete a note; yields deleted { id, at, by }. Its changes stay in the service's file. Admin.
326 #[plexus_rpc::macros::method(group = "admin", example(note = "gone", params = r#"{"id": "7k3mq2xa"}"#))]
327 pub async fn delete(
328 &self,
329 #[from_auth(self.callers.verify)] user: Caller,
330 /// Its id, e.g. 7k3mq2xa.
331 id: NoteId,
332 ) -> impl Stream<Item = NotesEvent> + Send + 'static {
333 let (store, seam) = (self.store.clone(), self.seam.clone());
334 once(crate::streams::delete(store, seam, user, id.into_string()))
335 }
336
337 /// Put a note's body back as it stood after a change; yields saved { id, revision, at, by } — the restore is a change more, merged like a save. Editor.
338 #[plexus_rpc::macros::method(group = "write", example(note = "back to change 2", params = r#"{"id": "7k3mq2xa", "seq": 2}"#))]
339 pub async fn restore(
340 &self,
341 #[from_auth(self.callers.verify)] user: Caller,
342 /// Its id, e.g. 7k3mq2xa.
343 id: NoteId,
344 /// The change to stand it at, e.g. 2 (`history`'s seq).
345 seq: u32,
346 ) -> impl Stream<Item = NotesEvent> + Send + 'static {
347 let (store, seam) = (self.store.clone(), self.seam.clone());
348 once(crate::streams::restore(store, seam, user, id.into_string(), seq))
349 }
350
351 /// Whether you hold a role on a note — viewer | editor | admin — as the gate says on its organization now; yields may { id, role, held }, or not_found for one you do not read.
352 ///
353 /// The question another service asks through the seam before it keeps
354 /// something of a note's, as the caller (the service that keeps
355 /// images asks `editor` before it keeps one for a note, `viewer`
356 /// before it answers one). Nothing is written. Viewer.
357 #[plexus_rpc::macros::method(group = "read", values(role = ["viewer", "editor", "admin"]), example(note = "may I write it?", params = r#"{"id": "7k3mq2xa", "role": "editor"}"#))]
358 pub async fn may(
359 &self,
360 #[from_auth(self.callers.verify)] user: Caller,
361 /// Its id, e.g. 7k3mq2xa.
362 id: NoteId,
363 /// The role asked: viewer | editor | admin.
364 role: Role,
365 ) -> impl Stream<Item = NotesEvent> + Send + 'static {
366 let (store, seam) = (self.store.clone(), self.seam.clone());
367 once(crate::streams::may(store, seam, user, id.into_string(), role))
368 }
369
370 /// Ask a question on a range of a note — it stays beside that text as the text changes; yields asked { thread }, said on watch.
371 ///
372 /// `from` and `to` are the range in characters of the text now (as
373 /// `get`'s body counts them). The range is anchored in the note's
374 /// CRDT, so it follows the text through every edit (`thread.from`,
375 /// `thread.to` where it stands now; deleted whole, the thread is
376 /// `detached`). `text` is the question (markdown: links, images).
377 /// `to_whom` asks it of an agent (`builder`, or `agent` for any); such
378 /// a question is listed by `waiting` and said to every watch of the
379 /// organization's notes, so an agent picks it up, and may answer
380 /// with `reply` or edit the note itself. Editor.
381 #[plexus_rpc::macros::method(group = "write", example(note = "a question on characters 10 to 42", params = r#"{"id": "7k3mq2xa", "from": 10, "to": 42, "text": "Is this still true after the move?", "to_whom": "agent"}"#))]
382 pub async fn ask(
383 &self,
384 #[from_auth(self.callers.verify)] user: Caller,
385 /// Its id, e.g. 7k3mq2xa.
386 id: NoteId,
387 /// Where the range starts, in characters, e.g. 10.
388 from: u32,
389 /// Where it ends, e.g. 42.
390 to: u32,
391 /// The question, markdown.
392 text: ThreadText,
393 /// Whom it is asked of: an agent's name, or agent for any (optional: anyone reading).
394 to_whom: Option<AgentName>,
395 ) -> impl Stream<Item = NotesEvent> + Send + 'static {
396 let (store, seam) = (self.store.clone(), self.seam.clone());
397 once(crate::streams::ask(store, seam, user, id.into_string(), from, to, text.into_string(), to_whom.map(AgentName::into_string)))
398 }
399
400 /// Answer in a thread — words, links, images; yields replied { thread }, said on watch. Editor.
401 #[plexus_rpc::macros::method(group = "write", example(note = "an answer", params = r#"{"id": "7k3mq2xa", "thread": "q4k9m2xa", "body": "Yes — see [the move](https://example.com)."}"#))]
402 pub async fn reply(
403 &self,
404 #[from_auth(self.callers.verify)] user: Caller,
405 /// The note's id, e.g. 7k3mq2xa.
406 id: NoteId,
407 /// The thread's id, as ask answered it.
408 thread: ThreadId,
409 /// The answer, markdown.
410 body: ThreadText,
411 ) -> impl Stream<Item = NotesEvent> + Send + 'static {
412 let (store, seam) = (self.store.clone(), self.seam.clone());
413 once(crate::streams::reply(store, seam, user, id.into_string(), thread.into_string(), body.into_string()))
414 }
415
416 /// Resolve a thread (it folds in the margin), or open it again; yields resolved { thread }, said on watch. Editor.
417 #[plexus_rpc::macros::method(group = "write", example(note = "done", params = r#"{"id": "7k3mq2xa", "thread": "q4k9m2xa"}"#))]
418 pub async fn resolve(
419 &self,
420 #[from_auth(self.callers.verify)] user: Caller,
421 /// The note's id, e.g. 7k3mq2xa.
422 id: NoteId,
423 /// The thread's id.
424 thread: ThreadId,
425 /// Open it again instead (optional: false).
426 open: Option<bool>,
427 ) -> impl Stream<Item = NotesEvent> + Send + 'static {
428 let (store, seam) = (self.store.clone(), self.seam.clone());
429 once(crate::streams::resolve(store, seam, user, id.into_string(), thread.into_string(), open.unwrap_or(false)))
430 }
431
432 /// A note's threads, in the order their ranges stand in the text, the detached ones last; yields thread { thread } each.
433 ///
434 /// Each thread is whole: its anchor (two Yjs relative positions, for a
435 /// page to resolve in its own copy), its range now in characters, the
436 /// text it quoted, the question, whom it was asked of, its answers, and
437 /// whether it is resolved. Viewer.
438 #[plexus_rpc::macros::method(group = "read", example(note = "the threads", params = r#"{"id": "7k3mq2xa"}"#))]
439 pub async fn threads(
440 &self,
441 #[from_auth(self.callers.verify)] user: Caller,
442 /// Its id, e.g. 7k3mq2xa.
443 id: NoteId,
444 ) -> impl Stream<Item = NotesEvent> + Send + 'static {
445 let (store, seam) = (self.store.clone(), self.seam.clone());
446 many(crate::streams::threads(store, seam, user, id.into_string()))
447 }
448
449 /// The open questions asked of someone, in the notes you read, oldest first; yields thread { thread } each — an agent's queue.
450 ///
451 /// `to` keeps those asked of that name (`builder`, or `agent` for the
452 /// ones asked of any agent). Viewer.
453 #[plexus_rpc::macros::method(group = "read", example(note = "what any agent is asked", params = r#"{"to": "agent"}"#))]
454 pub async fn waiting(
455 &self,
456 #[from_auth(self.callers.verify)] user: Caller,
457 /// Asked of this name only, e.g. agent (optional: of anyone named).
458 to: Option<AgentName>,
459 ) -> impl Stream<Item = NotesEvent> + Send + 'static {
460 let (store, seam) = (self.store.clone(), self.seam.clone());
461 many(crate::streams::waiting(store, seam, user, to.map(AgentName::into_string)))
462 }
463
464 /// NOTES-4: a note's slot whole; yields slot { slot: { id, fill?, props, fills, building? } } — what fills it now, its props, every fill newest first, the build under way.
465 ///
466 /// A fill is `{ n, component, version, say?, by, principal, at }`; a
467 /// build `{ component, step?, say?, failed, by, principal, started, at }`.
468 /// The page draws `fill` by a mark pinned to its version. Viewer.
469 #[plexus_rpc::macros::method(group = "read", example(note = "the slot", params = r#"{"id": "7k3mq2xa"}"#))]
470 pub async fn slot(
471 &self,
472 #[from_auth(self.callers.verify)] user: Caller,
473 /// The note's id, e.g. 7k3mq2xa.
474 id: NoteId,
475 ) -> impl Stream<Item = NotesEvent> + Send + 'static {
476 let (store, seam) = (self.store.clone(), self.seam.clone());
477 once(crate::slot_calls::slot(store, seam, user, id.into_string()))
478 }
479
480 /// NOTES-4: fill a note's slot with a component of a kept version; yields filled { slot }, said on watch as slot_changed; the build under way ends.
481 ///
482 /// The ui service is asked whether `version` (a hash, or its first 6 hex
483 /// digits or more) holds `component`: refused `unknown_version` or
484 /// `unknown_component` naming both, the slot unchanged. `props` replaces
485 /// the slot's props (none: they stay); `say` is one line of what this
486 /// fill does. Every open page draws it in place. Editor.
487 #[plexus_rpc::macros::method(group = "write", example(note = "graph-nodes, as authored", params = r#"{"id": "7k3mq2xa", "component": "graph-nodes", "version": "3f9a1c0b7d2e", "say": "click two nodes to connect"}"#))]
488 pub async fn fill(
489 &self,
490 #[from_auth(self.callers.verify)] user: Caller,
491 /// The note's id, e.g. 7k3mq2xa.
492 id: NoteId,
493 /// The component, e.g. graph-nodes.
494 component: ComponentName,
495 /// The version it is of, as ui.author answered it.
496 version: VersionRef,
497 /// The props it starts from, a JSON object (optional: the slot's stay).
498 props: Option<SlotProps>,
499 /// What this fill does, one line (optional).
500 say: Option<SlotSay>,
501 ) -> impl Stream<Item = NotesEvent> + Send + 'static {
502 let (store, seam) = (self.store.clone(), self.seam.clone());
503 let (props, say) = (props.map(SlotProps::into_map), say.map(SlotSay::into_string));
504 once(crate::slot_calls::fill(store, seam, user, id.into_string(), component.into_string(), version.into_string(), props, say))
505 }
506
507 /// NOTES-4: empty a note's slot — nothing drawn, its props cleared, its fills kept; yields emptied { slot }, said on watch as slot_changed. Editor.
508 #[plexus_rpc::macros::method(group = "write", example(note = "nothing in it", params = r#"{"id": "7k3mq2xa"}"#))]
509 pub async fn empty(
510 &self,
511 #[from_auth(self.callers.verify)] user: Caller,
512 /// The note's id, e.g. 7k3mq2xa.
513 id: NoteId,
514 ) -> impl Stream<Item = NotesEvent> + Send + 'static {
515 let (store, seam) = (self.store.clone(), self.seam.clone());
516 once(crate::slot_calls::empty(store, seam, user, id.into_string()))
517 }
518
519 /// NOTES-4: say a slot is being built — a step, a line, a failure; yields building { slot }, said on watch as building_changed.
520 ///
521 /// `step` is the last reached: `heard`, `written` or `compiled`; `say`
522 /// one line; `failed: true` with `say` holding the refusal (the
523 /// compiler's line) marks a build that failed. The component that is in
524 /// the slot stays drawn. A fill or an empty ends it; so do ten minutes
525 /// without a word, and a restart: it is kept in memory only. Editor.
526 #[plexus_rpc::macros::method(group = "write", values(step = ["heard", "written", "compiled"]), example(note = "the source is written", params = r#"{"id": "7k3mq2xa", "component": "graph-nodes", "step": "written", "say": "drag a node"}"#))]
527 pub async fn building(
528 &self,
529 #[from_auth(self.callers.verify)] user: Caller,
530 /// The note's id, e.g. 7k3mq2xa.
531 id: NoteId,
532 /// The component being built, e.g. graph-nodes.
533 component: ComponentName,
534 /// The last step reached: heard | written | compiled (optional).
535 step: Option<BuildStep>,
536 /// One line — with failed, the refusal (optional).
537 say: Option<SlotSay>,
538 /// The build failed (optional: false).
539 failed: Option<bool>,
540 ) -> impl Stream<Item = NotesEvent> + Send + 'static {
541 let (store, seam) = (self.store.clone(), self.seam.clone());
542 let (component, say) = (component.into_string(), say.map(SlotSay::into_string));
543 once(crate::slot_calls::building(store, seam, user, id.into_string(), component, step, say, failed.unwrap_or(false)))
544 }
545
546 /// NOTES-4: merge a patch into a slot's props — what its component keeps its state in; yields props { slot }, said on watch as props_changed { id, props, by, slot }.
547 ///
548 /// A key set to `null` is taken away. The props are held to 64 KiB
549 /// written as JSON: past it, `refused { too_large }` and nothing
550 /// written. Every page open on the note hands the new props to the
551 /// component it has mounted. Editor.
552 #[plexus_rpc::macros::method(group = "write", example(note = "a line added", params = r#"{"id": "7k3mq2xa", "patch": {"lines": [["tickets", "ui"]]}}"#))]
553 pub async fn props(
554 &self,
555 #[from_auth(self.callers.verify)] user: Caller,
556 /// The note's id, e.g. 7k3mq2xa.
557 id: NoteId,
558 /// The patch, a JSON object: each key set, a null taken away.
559 patch: SlotProps,
560 ) -> impl Stream<Item = NotesEvent> + Send + 'static {
561 let (store, seam) = (self.store.clone(), self.seam.clone());
562 once(crate::slot_calls::props(store, seam, user, id.into_string(), patch.into_map()))
563 }
564
565 /// Mark a range of a note — an underline that follows its words, with a link, a line of state, a component under its passage, or any of them; or change a mark; yields marked { mark }, said on watch. The note's text is not changed.
566 ///
567 /// A new mark names `from` and `to`, the range in characters of the
568 /// text now (as `get`'s body counts them); it is anchored in the note's
569 /// CRDT as a question's range is, so it follows its words through every
570 /// edit (`mark.from`, `mark.to` where they stand now; every character
571 /// deleted, it is `detached`, kept and drawn nowhere). With `mark`
572 /// instead, that mark is changed: its `link` and `label` set as given,
573 /// an empty one taken off. `link` is a ticket (`KILN-12`), an address of
574 /// the app (`#/…`) or an `https` address; a click on the underline opens
575 /// it. `label` is one line of state, drawn under the passage with who
576 /// left it. `component` and `version` place a component of a version the
577 /// ui service keeps under the passage that holds the range — never in
578 /// the text — with `props` its props (a JSON object, at most 64 KiB):
579 /// the ui service is asked whether the version holds it, refused
580 /// `unknown_version` or `unknown_component` naming both, nothing written;
581 /// `mark_props` patches the props after. Nothing here writes the note:
582 /// its body and its revision stay as they are. Editor.
583 #[plexus_rpc::macros::method(group = "write", example(note = "the first sentence, linked to the ticket filed from it", params = r#"{"id": "7k3mq2xa", "from": 0, "to": 40, "link": "KILN-12", "label": "filed KILN-12"}"#))]
584 pub async fn mark(
585 &self,
586 #[from_auth(self.callers.verify)] user: Caller,
587 /// The note's id, e.g. 7k3mq2xa.
588 id: NoteId,
589 /// Where a new mark's range starts, in characters, e.g. 0 (optional: with mark, none).
590 from: Option<u32>,
591 /// Where it ends, e.g. 40 (optional: with mark, none).
592 to: Option<u32>,
593 /// The mark to change, as mark answered it (optional: a new mark).
594 mark: Option<MarkId>,
595 /// What a click on it opens: a ticket, e.g. KILN-12, an address of the app (#/…) or an https address (optional; empty takes it off).
596 link: Option<MarkLink>,
597 /// One line of state, e.g. filed KILN-12 (optional; empty takes it off).
598 label: Option<MarkLabel>,
599 /// A component to place under the passage, e.g. node-legend (optional; with version).
600 component: Option<ComponentName>,
601 /// The kept version that holds it: its hash, or its first 6 hex digits or more (optional; with component).
602 version: Option<VersionRef>,
603 /// The component's props, a JSON object, e.g. {"stopped": true} (optional: {}; replaces what it held).
604 props: Option<SlotProps>,
605 ) -> impl Stream<Item = NotesEvent> + Send + 'static {
606 let (store, seam) = (self.store.clone(), self.seam.clone());
607 let of = crate::marks::Remark { link: link.map(MarkLink::into_string), label: label.map(MarkLabel::into_string), placed: None, props: props.map(SlotProps::into_map) };
608 once(crate::streams::mark(store, seam, user, id.into_string(), mark.map(MarkId::into_string), from, to, of, component.map(ComponentName::into_string), version.map(VersionRef::into_string)))
609 }
610
611 /// Merge a patch into the props of the component a mark places — what the component keeps its state in; yields marked { mark }, said on watch as mark_changed. The note's text is not changed.
612 ///
613 /// A key set to `null` is taken away. The props are held to 64 KiB
614 /// written as JSON: past it, `refused { too_large }` and nothing
615 /// written; a mark that places no component is `refused { no_component }`.
616 /// Every page open on the note hands the new props to the component it
617 /// has mounted under the passage, in place. Editor.
618 #[plexus_rpc::macros::method(group = "write", example(note = "the stopped services shown", params = r#"{"id": "7k3mq2xa", "mark": "m4k9q2xa", "patch": {"stopped": true}}"#))]
619 pub async fn mark_props(
620 &self,
621 #[from_auth(self.callers.verify)] user: Caller,
622 /// The note's id, e.g. 7k3mq2xa.
623 id: NoteId,
624 /// The mark's id, as mark answered it.
625 mark: MarkId,
626 /// The patch, a JSON object: each key set, a null taking it away.
627 patch: SlotProps,
628 ) -> impl Stream<Item = NotesEvent> + Send + 'static {
629 let (store, seam) = (self.store.clone(), self.seam.clone());
630 once(crate::streams::mark_props(store, seam, user, id.into_string(), mark.into_string(), patch.into_map()))
631 }
632
633 /// Take a mark off a note; yields unmarked { id, mark }, said on watch as mark_removed. The note's text is not changed. Editor.
634 #[plexus_rpc::macros::method(group = "write", example(note = "a mark taken off", params = r#"{"id": "7k3mq2xa", "mark": "m4k9q2xa"}"#))]
635 pub async fn unmark(
636 &self,
637 #[from_auth(self.callers.verify)] user: Caller,
638 /// The note's id, e.g. 7k3mq2xa.
639 id: NoteId,
640 /// The mark's id, as mark answered it.
641 mark: MarkId,
642 ) -> impl Stream<Item = NotesEvent> + Send + 'static {
643 let (store, seam) = (self.store.clone(), self.seam.clone());
644 once(crate::streams::unmark(store, seam, user, id.into_string(), mark.into_string()))
645 }
646
647 /// A note's marks, in the order their ranges stand in the text, the detached ones last; yields mark { mark } each — where each stands now and the words it holds.
648 ///
649 /// Each mark is whole: its anchor (two Yjs relative positions, for a page
650 /// to resolve in its own copy), its range now in characters (`from`,
651 /// `to`), the `words` it holds now and the `quote` it held when made,
652 /// its link and label, who left it and when. Viewer.
653 #[plexus_rpc::macros::method(group = "read", example(note = "the marks", params = r#"{"id": "7k3mq2xa"}"#))]
654 pub async fn marks(
655 &self,
656 #[from_auth(self.callers.verify)] user: Caller,
657 /// Its id, e.g. 7k3mq2xa.
658 id: NoteId,
659 ) -> impl Stream<Item = NotesEvent> + Send + 'static {
660 let (store, seam) = (self.store.clone(), self.seam.clone());
661 many(crate::streams::marks(store, seam, user, id.into_string()))
662 }
663
664 /// Follow notes: watching { id? } first, then created, updated { id, seq, update, by }, renamed, deleted, squashed, asked, replied, resolved, slot_changed, building_changed, props_changed, mark_changed, mark_removed — and, on one note, present and left, and with text the body as words — as they happen; open-ended, ends with watch_closed { reason, message }.
665 ///
666 /// With `id`, one note's: each `updated` carries the Yjs update to
667 /// apply (the stream ends after its `deleted`), and who comes and goes
668 /// (`present { present }`, `left { session, client? }`); with `session`
669 /// as well, this watch is your presence on it while it is open, and your
670 /// own updates (sent with that session) are not said back. Without `id`,
671 /// every note's you read, `note` without its body. Held to you by the
672 /// gate: asked again when the grants move, a sign-out or the expiry comes,
673 /// and closed with a typed reason (`signed_out`, `expired`, `revoked`,
674 /// `refused`); each write is asked of the gate on its organization as it
675 /// stands then. `lagged { missed }` when it fell behind: read again
676 /// (`state` with your vector). NOTES-5: `mark_changed { id, mark }` (a
677 /// mark made or changed, whole) and `mark_removed { id, mark }`; with
678 /// `text: true` (and `id`) the note's markdown as words — `text { id,
679 /// revision, body, by, at }` once as the watch opens, then a second
680 /// after the first change not yet said, holding every change since:
681 /// at most one a second, the last change always said. Viewer.
682 #[plexus_rpc::macros::method(group = "read")]
683 pub async fn watch(
684 &self,
685 #[from_auth(self.callers.verify)] user: Caller,
686 /// One note's id, e.g. 7k3mq2xa (optional: every note you read).
687 id: Option<NoteId>,
688 /// Your page's session on it, e.g. s-3f9a1c — you are present while the watch is open (optional; with id only).
689 session: Option<NoteSession>,
690 /// true: the note's markdown as words, text { id, revision, body, by, at }, as it is written (optional: false; with id only).
691 text: Option<bool>,
692 ) -> impl Stream<Item = NotesEvent> + Send + 'static {
693 crate::watch::watch(self.store.clone(), self.seam.clone(), user, id.map(NoteId::into_string), session.map(NoteSession::into_string), text.unwrap_or(false))
694 }
695
696 /// Every principal's notes made and bytes written (admin of *): yields usage { principal, count, bytes } each — what quota.recount reads.
697 ///
698 /// V2-31: from the changes kept — `count` the notes a principal
699 /// made, `bytes` every change they wrote (a squash's snapshot is
700 /// nobody's). Admin of `*`: KEEL-48, `everywhere` — the gate refuses a
701 /// holder on a narrower scope before it runs.
702 #[plexus_rpc::macros::method(group = "read", everywhere, example(note = "every author", params = r#"{"everyone": true}"#))]
703 pub async fn usage(
704 &self,
705 #[from_auth(self.callers.verify)] _user: Caller,
706 /// true: every principal (the only reading there is).
707 everyone: Option<bool>,
708 /// V2-70: by the day each change was kept — usage_day { principal, day, count, bytes } (what quota history is backfilled from).
709 daily: Option<bool>,
710 ) -> impl Stream<Item = NotesEvent> + Send + 'static {
711 let _ = everyone;
712 many(crate::streams::usage(self.store.clone(), daily.unwrap_or(false)))
713 }
714}