Skip to main content

vvv_engine/protocol/
request.rs

1//! Every request as one value, and every answer as one: what a client sends
2//! down a wire and reads back. `{"command": "rename", "name": "Config",
3//! "to": "Settings", "apply": true}` is a [`Request`]; the reply's `result`
4//! is the [`Answer`] of the same name.
5
6use serde::{Deserialize, Serialize};
7#[cfg(test)]
8use vvv_core::Query;
9
10use crate::capabilities::moves::{Move, MoveIntent, MoveSymbol, MoveSymbolIntent};
11use crate::capabilities::rename::{Rename, RenameIntent};
12
13use super::{
14    Batch, BatchIntent, Dead, DeadQuery, Deps, DepsQuery, ExplainQuery, Explanation, File,
15    FileQuery, History, Impact, ImpactQuery, ImportsQuery, ImportsReport, Locations,
16    MutationAnswer, Notice, Outline, OutlineQuery, References, ReferencesQuery, Response, Rewrite,
17    RewriteIntent, Search, Surface, SurfaceQuery, Undo, WhereQuery,
18};
19
20/// One request, tagged by `command`. A mutation carries the same fields as
21/// its [`Intent`](super::Intent) plus `apply`: false previews, true writes
22/// and records one undo — exactly what the CLI's `--apply` does.
23#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
24#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
25#[serde(tag = "command", rename_all = "snake_case")]
26pub enum Request {
27    DiscardPlan(crate::DiscardPlanQuery),
28    ApplyPlan(crate::ApplyPlanQuery),
29    ValidatePlan(crate::ValidatePlanQuery),
30    InspectPlan(crate::InspectPlanQuery),
31    PrepareRename(crate::PrepareRenameQuery),
32    PrepareRewrite(crate::PrepareRewriteQuery),
33    PrepareMove(crate::PrepareMoveQuery),
34    PrepareMoveSymbol(crate::PrepareMoveSymbolQuery),
35    SymbolMoveCandidates(crate::SymbolMoveCandidatesQuery),
36    ReviewPlan(crate::ReviewPlanQuery),
37    #[cfg(feature = "schema")]
38    Schema(crate::SchemaQuery),
39    SearchPage(crate::SearchPageQuery),
40    ContextPage(crate::ContextPageQuery),
41    Continue(crate::ContinueQuery),
42    Expand(crate::ExpandQuery),
43    Discover(crate::DiscoveryQuery),
44    Context(crate::ContextQuery),
45    Navigate(crate::NavigationQuery),
46    Relationships(crate::RelationshipsQuery),
47    Resolve(crate::ResolutionQuery),
48    Search(crate::SearchQuery),
49    Outline(OutlineQuery),
50    References(ReferencesQuery),
51    Where(WhereQuery),
52    Deps(DepsQuery),
53    Explain(ExplainQuery),
54    Surface(SurfaceQuery),
55    Impact(ImpactQuery),
56    Dead(DeadQuery),
57    Imports(ImportsQuery),
58    WorkspaceFiles(crate::WorkspaceFilesQuery),
59    File(FileQuery),
60    Rewrite {
61        #[serde(flatten)]
62        intent: RewriteIntent,
63        #[serde(default)]
64        apply: bool,
65    },
66    Rename {
67        #[serde(flatten)]
68        intent: RenameIntent,
69        #[serde(default)]
70        apply: bool,
71    },
72    Move {
73        #[serde(flatten)]
74        intent: MoveIntent,
75        #[serde(default)]
76        apply: bool,
77    },
78    MoveSymbol {
79        #[serde(flatten)]
80        intent: MoveSymbolIntent,
81        #[serde(default)]
82        apply: bool,
83    },
84    Batch {
85        #[serde(flatten)]
86        intent: BatchIntent,
87        #[serde(default)]
88        apply: bool,
89    },
90    History,
91    Undo,
92}
93
94impl Request {
95    /// Whether running this request can write. The picker's hub asks only
96    /// these; a mutation goes through an `Intent` and `Apply`.
97    /// Reads and explicit checks can stop; applying a transaction cannot.
98    pub fn is_cancellable(&self) -> bool {
99        self.is_read_only() || matches!(self, Self::ValidatePlan(_))
100    }
101    pub fn is_read_only(&self) -> bool {
102        self.command().is_read_only()
103    }
104
105    pub fn command(&self) -> super::Command {
106        match self {
107            Self::DiscardPlan(_) => super::Command::DiscardPlan,
108            Self::ApplyPlan(_) => super::Command::ApplyPlan,
109            Self::ValidatePlan(_) => super::Command::ValidatePlan,
110            Self::InspectPlan(_) => super::Command::InspectPlan,
111            Self::PrepareRename(_) => super::Command::PrepareRename,
112            Self::PrepareRewrite(_) => super::Command::PrepareRewrite,
113            Self::PrepareMove(_) => super::Command::PrepareMove,
114            Self::PrepareMoveSymbol(_) => super::Command::PrepareMoveSymbol,
115            Self::SymbolMoveCandidates(_) => super::Command::SymbolMoveCandidates,
116            Self::ReviewPlan(_) => super::Command::ReviewPlan,
117            #[cfg(feature = "schema")]
118            Self::Schema(_) => super::Command::Schema,
119            Self::SearchPage(_) => super::Command::SearchPage,
120            Self::ContextPage(_) => super::Command::ContextPage,
121            Self::Continue(_) => super::Command::Continue,
122            Self::Expand(_) => super::Command::Expand,
123            Self::Discover(_) => super::Command::Discover,
124            Self::Context(_) => super::Command::Context,
125            Self::Navigate(_) => super::Command::Navigate,
126            Self::Relationships(_) => super::Command::Relationships,
127            Self::Resolve(_) => super::Command::Resolve,
128            Self::Search(_) => super::Command::Search,
129            Self::Outline(_) => super::Command::Outline,
130            Self::References(_) => super::Command::References,
131            Self::Where(_) => super::Command::Where,
132            Self::Deps(_) => super::Command::Deps,
133            Self::Explain(_) => super::Command::Explain,
134            Self::Surface(_) => super::Command::Surface,
135            Self::Impact(_) => super::Command::Impact,
136            Self::Dead(_) => super::Command::Dead,
137            Self::Imports(_) => super::Command::Imports,
138            Self::WorkspaceFiles(_) => super::Command::WorkspaceFiles,
139            Self::File(_) => super::Command::File,
140            Self::Rewrite { .. } => super::Command::Rewrite,
141            Self::Rename { .. } => super::Command::Rename,
142            Self::Move { .. } => super::Command::Move,
143            Self::MoveSymbol { .. } => super::Command::MoveSymbol,
144            Self::Batch { .. } => super::Command::Batch,
145            Self::History => super::Command::History,
146            Self::Undo => super::Command::Undo,
147        }
148    }
149}
150
151/// The answer to a [`Request`]: the result type of the command asked. On
152/// the wire it is that type's shape alone — a client knows what it asked —
153/// so it serialises without a tag and is read back by the command's type.
154#[derive(Debug, Clone, Serialize)]
155#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
156#[serde(untagged)]
157// Built once and serialised once: the largest result's size is not a cost
158// worth a `Box` in every client's match.
159#[allow(clippy::large_enum_variant)]
160pub enum Answer {
161    DiscardPlan(crate::PlanReview),
162    ApplyPlan(crate::PlanReceipt),
163    ValidatePlan(crate::ValidationReport),
164    InspectPlan(crate::PlanReviewReply),
165    PrepareRename(crate::PlanReviewReply),
166    PrepareRewrite(crate::PlanReviewReply),
167    PrepareMove(crate::PlanReviewReply),
168    PrepareMoveSymbol(crate::PlanReviewReply),
169    SymbolMoveCandidates(crate::SymbolMoveCandidates),
170    ReviewPlan(crate::PlanReviewPage),
171    #[cfg(feature = "schema")]
172    Schema(crate::SchemaDocument),
173    SearchPage(crate::SearchPage),
174    ContextPage(crate::ContextPage),
175    Continue(crate::PageReply),
176    Expand(crate::Expansion),
177    Discover(crate::Discovery),
178    Context(crate::ContextReply),
179    Navigate(crate::NavigationReply),
180    Relationships(crate::Relationships),
181    Resolve(crate::ResolutionReply),
182    Search(Search),
183    Outline(Outline),
184    References(References),
185    Where(Locations),
186    Deps(Deps),
187    Explain(Explanation),
188    Surface(Surface),
189    Impact(Impact),
190    Dead(Dead),
191    Imports(ImportsReport),
192    WorkspaceFiles(crate::WorkspaceFiles),
193    File(File),
194    Rewrite(Rewrite),
195    Rename(Rename),
196    Move(Move),
197    MoveSymbol(MoveSymbol),
198    Batch(Batch),
199    History(History),
200    Undo(Undo),
201}
202
203impl Answer {
204    /// The notices a mutating answer leaves to a person, if any.
205    pub fn notices(&self) -> &[Notice] {
206        match self {
207            Self::Move(m) => &m.notices,
208            Self::MoveSymbol(m) => &m.notices,
209            Self::Batch(b) => &b.notices,
210            _ => &[],
211        }
212    }
213
214    /// The history entry a written answer recorded, if any.
215    pub fn history_id(&self) -> Option<u64> {
216        match self {
217            Self::ApplyPlan(r) => Some(r.history_id),
218            Self::Rewrite(r) => r.state.history_id(),
219            Self::Rename(r) => r.state.history_id(),
220            Self::Move(r) => r.state.history_id(),
221            Self::MoveSymbol(r) => r.state.history_id(),
222            Self::Batch(b) => b.state.history_id(),
223            _ => None,
224        }
225    }
226}
227
228impl From<MutationAnswer> for Answer {
229    fn from(result: MutationAnswer) -> Self {
230        match result {
231            MutationAnswer::Rewrite(result) => Self::Rewrite(result),
232            MutationAnswer::Rename(result) => Self::Rename(result),
233            MutationAnswer::Move(result) => Self::Move(result),
234            MutationAnswer::MoveSymbol(result) => Self::MoveSymbol(result),
235            MutationAnswer::Batch(result) => Self::Batch(result),
236        }
237    }
238}
239
240/// A request on a session's wire (`vvv serve`): the request with whatever
241/// `id` the caller chose, echoed on the [`Reply`].
242#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
243#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
244pub struct Call {
245    #[serde(default, skip_serializing_if = "Option::is_none")]
246    #[cfg_attr(feature = "schema", schemars(range(min = crate::ContextBudget::MIN_BYTES, max = crate::ContextBudget::MAX_BYTES)))]
247    pub max_output_bytes: Option<usize>,
248    #[serde(default, skip_serializing_if = "Option::is_none")]
249    pub id: Option<serde_json::Value>,
250    #[serde(flatten)]
251    pub request: Request,
252}
253
254/// The reply to a [`Call`]: its `id`, then the usual envelope.
255#[derive(Debug, Clone, Serialize, Deserialize)]
256#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
257pub struct Reply<T> {
258    #[serde(default, skip_serializing_if = "Option::is_none")]
259    pub id: Option<serde_json::Value>,
260    #[serde(flatten)]
261    pub response: Response<T>,
262}
263
264#[cfg(test)]
265mod tests {
266    use super::*;
267
268    #[test]
269    fn the_read_only_guard_separates_queries_from_mutations() {
270        assert!(Request::History.is_read_only());
271        assert!(Request::Search(Query::pattern("Engine").into()).is_read_only());
272        assert!(Request::References(ReferencesQuery::new("Engine")).is_read_only());
273        assert!(!Request::Undo.is_read_only(), "undo writes, however small");
274        assert!(
275            !Request::Rename {
276                intent: RenameIntent::new("A", "B"),
277                apply: false,
278            }
279            .is_read_only()
280        );
281        assert!(
282            !Request::Batch {
283                intent: BatchIntent { intents: vec![] },
284                apply: false,
285            }
286            .is_read_only()
287        );
288    }
289}