Skip to main content

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}