onetaskgraph_plugin_api/source.rs
1//! The two traits a plugin implements, and the secret lookup it is handed.
2
3use schemars::{JsonSchema, Schema};
4use secrecy::SecretString;
5use serde::{Deserialize, Serialize};
6
7use crate::{
8 Capabilities, DependencyEdge, Direction, ItemWrite, Label, NativeId, Page, PageRequest,
9 Project, ProjectQuery, SourceError, SourceName, Task, TaskQuery, WriteSupport, unwritable,
10};
11
12/// Whether a source is answering right now.
13///
14/// # Placement is an open contract question
15///
16/// This type lives here because [`TaskSource::health`] returns it and the trait
17/// lives here: placing it in `onetaskgraph-core` would make this crate depend on
18/// the engine and invert the one direction the crate split exists to establish.
19/// The approved contract enumerates this crate's contents exhaustively and does
20/// not name `Health`, so the enumeration and the trait as written cannot both
21/// stand. Compiling forces the placement below; the resolution — add it to the
22/// enumeration, or redesign `health` so no such type crosses the boundary —
23/// belongs to the contract's owner, not to this crate. See `AGENTS.md`.
24#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
25// llmlint: ignore[invalid_states_unrepresentable] SECOND PERMITTED REASON — this restates at a new site the justification already recorded at `Capabilities.max_page_size` (capability.rs) and `PageRequest.limit` (query.rs), and a third time in this type's own doc comment above and in AGENTS.md's "Open contract question — `Health`": `Health`'s shape is approved contract text that `TaskSource::health` returns, so an enum here would change the serialized form and the trait six undispatched nodes implement. That is the contract owner's call, not this crate's.
26pub struct Health {
27 /// Whether the source answered.
28 ///
29 /// A bare `bool` beside an untyped `detail` cannot say that an unreachable source
30 /// must explain itself, or keep "reachable with a warning" apart from "reachable";
31 /// an enum carrying the detail in its unreachable variant would.
32 // llmlint: ignore[invalid_states_unrepresentable] SECOND PERMITTED REASON — this
33 // restates at this field the justification already recorded at
34 // `Capabilities.max_page_size` (capability.rs), `PageRequest.limit` (query.rs), this
35 // type's own doc comment above, and AGENTS.md's "Open contract question — `Health`":
36 // `Health`'s shape is approved contract text that `TaskSource::health` returns, so an
37 // enum here would change the serialized form and the trait six undispatched nodes
38 // implement. That is the contract owner's call, not this crate's.
39 // llmlint: ignore[boundary_inputs_validated] making "unreachable with no reason given" unrepresentable means an enum here, which changes the serialized form and the trait six undispatched nodes implement. Deferred to the contract's owner — AGENTS.md, "Open contract question — `Health`".
40 pub reachable: bool,
41 /// What the source said, when it said anything useful.
42 pub detail: Option<String>,
43}
44
45/// One configured source, as the engine drives it.
46///
47/// Dyn-compatible through `async_trait` because the engine holds
48/// `Vec<Box<dyn TaskSource>>` over heterogeneous plugins.
49///
50/// Three rules bind every implementation, and the engine's compensation is only
51/// correct while all three hold:
52///
53/// 1. **Apply** every predicate you declare [`Support::Native`](crate::Support::Native).
54/// 2. **Ignore** every [`Support`](crate::Support)-typed predicate you declare
55/// `Unsupported` — return the *wider* result set, never a narrower one.
56/// Silently dropping rows for a predicate you did not declare is the one
57/// failure no test above the plugin can catch.
58/// 3. Never return a silently empty dependency read. Rule 2 reaches the
59/// `Support`-typed predicates alone; a dependency read is always real.
60#[async_trait::async_trait]
61pub trait TaskSource: Send + Sync {
62 /// The plugin kind that built this source, for display and for plan output.
63 fn kind(&self) -> &'static str;
64
65 /// What this source applies itself. Read once per query by the engine.
66 fn capabilities(&self) -> Capabilities;
67
68 /// Whether the source is answering right now.
69 ///
70 /// # Errors
71 ///
72 /// Returns a [`SourceError`] when the check itself could not be made.
73 async fn health(&self) -> Result<Health, SourceError>;
74
75 /// Fetch one task by its native id, or `None` when there is no such task.
76 ///
77 /// # Errors
78 ///
79 /// Returns a [`SourceError`] when the source could not answer.
80 async fn get_task(&self, id: &NativeId) -> Result<Option<Task>, SourceError>;
81
82 /// Fetch one project by its native id, or `None` when there is no such project.
83 ///
84 /// # Errors
85 ///
86 /// Returns a [`SourceError`] when the source could not answer.
87 async fn get_project(&self, id: &NativeId) -> Result<Option<Project>, SourceError>;
88
89 /// One page of the tasks matching `query`.
90 ///
91 /// # Errors
92 ///
93 /// Returns a [`SourceError`] when the source could not answer.
94 async fn query_tasks(
95 &self,
96 query: &TaskQuery,
97 page: &PageRequest,
98 ) -> Result<Page<Task>, SourceError>;
99
100 /// One page of the projects matching `query`.
101 ///
102 /// # Errors
103 ///
104 /// Returns a [`SourceError`] when the source could not answer.
105 async fn query_projects(
106 &self,
107 query: &ProjectQuery,
108 page: &PageRequest,
109 ) -> Result<Page<Project>, SourceError>;
110
111 /// One page of every label this source knows.
112 ///
113 /// # Errors
114 ///
115 /// Returns a [`SourceError`] when the source could not answer.
116 async fn labels(&self, page: &PageRequest) -> Result<Page<Label>, SourceError>;
117
118 /// One page of the task dependency edges at `id`, in `direction`.
119 ///
120 /// # Errors
121 ///
122 /// Returns a [`SourceError`] when the source could not answer.
123 async fn task_dependencies(
124 &self,
125 id: &NativeId,
126 direction: Direction,
127 page: &PageRequest,
128 ) -> Result<Page<DependencyEdge>, SourceError>;
129
130 /// One page of the project dependency edges at `id`, in `direction`.
131 ///
132 /// # Errors
133 ///
134 /// Returns a [`SourceError`] when the source could not answer.
135 async fn project_dependencies(
136 &self,
137 id: &NativeId,
138 direction: Direction,
139 page: &PageRequest,
140 ) -> Result<Page<DependencyEdge>, SourceError>;
141
142 /// Whether this source can be written through at all.
143 ///
144 /// Defaulted to [`WriteSupport::Unsupported`], which is what keeps this a read
145 /// interface for every source that has nothing to write into: one that cannot be
146 /// written needs no edit and keeps working. Read before a write is attempted, so a
147 /// copy naming such a source as its destination is refused before anything is read.
148 fn writes(&self) -> WriteSupport {
149 WriteSupport::Unsupported
150 }
151
152 /// Create or update one task, answering with the native id the destination holds it
153 /// under.
154 ///
155 /// A source declaring [`WriteSupport::Supported`] owes three things here. It refuses,
156 /// naming the field, anything it cannot represent rather than dropping it — including
157 /// a metadata key it cannot carry, which it names. It writes every other field it was
158 /// given. And it never creates when [`ItemWrite::target`] names an item it does not
159 /// hold.
160 ///
161 /// # Errors
162 ///
163 /// Returns [`SourceError::Refused`] when this source has no write side, when a field
164 /// or a metadata key cannot be represented, or when `target` names nothing here; and
165 /// whatever else the source could not do the write for.
166 async fn write_task(&self, write: &ItemWrite<Task>) -> Result<NativeId, SourceError> {
167 let _ = write;
168 Err(unwritable(self.kind()))
169 }
170
171 /// Create or update one project, on exactly the terms of
172 /// [`write_task`](Self::write_task).
173 ///
174 /// # Errors
175 ///
176 /// As [`write_task`](Self::write_task).
177 async fn write_project(&self, write: &ItemWrite<Project>) -> Result<NativeId, SourceError> {
178 let _ = write;
179 Err(unwritable(self.kind()))
180 }
181}
182
183/// The factory that turns one configuration block into a live [`TaskSource`].
184///
185/// Having the compile-time registry and the subprocess seam be the same shape is
186/// the whole reason this is a trait rather than a free function.
187pub trait SourcePlugin: Send + Sync + 'static {
188 /// The name a configuration document's `plugin:` field names.
189 fn kind(&self) -> &'static str;
190
191 /// The JSON Schema for this plugin's own `config:` block.
192 fn config_schema(&self) -> Schema;
193
194 /// Build a live source from one configuration block.
195 ///
196 /// `name` is the configured source's name, for error messages only — a
197 /// plugin never learns it for any other purpose.
198 ///
199 /// # Errors
200 ///
201 /// Returns [`SourceError::Config`] when `config` is not valid for this
202 /// plugin, or [`SourceError::Auth`] when a named credential is absent.
203 fn build(
204 &self,
205 name: &SourceName,
206 config: &serde_json::Value,
207 secrets: &dyn SecretResolver,
208 ) -> Result<Box<dyn TaskSource>, SourceError>;
209}
210
211/// How a plugin reads the credential its configuration names.
212///
213/// A configuration document never carries a credential value, only the name of
214/// the environment variable holding it.
215pub trait SecretResolver: Send + Sync {
216 /// The value of `var`, or `None` when nothing defines it.
217 ///
218 /// The returned value is never logged and never appears in `Debug` output.
219 fn get(&self, var: &str) -> Option<SecretString>;
220}