Skip to content
Sign up

flagon-io/g1t

public
0
491 linesCodeBlameRaw
1//! The integrations service: a workspace's connections to systems outside
2//! g1t, and everything that crosses between them.
3//!
4//! - **AI providers.** A workspace keeps the credentials for the AI
5//! providers its team uses (Anthropic, OpenAI, Gemini, and anything
6//! compatible with either API), sealed, so work can be handed to them.
7//! Workspace admins add, test, update and remove them.
8//! - **Alerts.** Sentry, Datadog or any signed webhook opens an issue in a
9//! repository, once per problem however often it fires.
10//! - **Trackers.** A Jira or Linear key, such as `TECH-1234`, resolves to the
11//! ticket: people and their tools read it, people import it as an issue,
12//! and when the work lands the ticket is told.
13//!
14//! Mirrors `packages/contracts/src/integrations.ts`.
15
16use serde::{Deserialize, Serialize};
17
18use crate::repos::RepoPath;
19use crate::{User, Viewer};
20
21/// Which outside system a connection is to.
22#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
23#[serde(rename_all = "snake_case")]
24pub enum Provider {
25 // Model providers: the labs.
26 Anthropic,
27 Openai,
28 /// Through Gemini's OpenAI-compatible endpoint.
29 Gemini,
30 Xai,
31 Mistral,
32 Deepseek,
33 // Model providers: platforms that serve many labs' models.
34 /// A deployment on the workspace's own Azure OpenAI resource.
35 AzureOpenai,
36 Openrouter,
37 Groq,
38 Together,
39 Fireworks,
40 Cerebras,
41 // Model providers: anything else.
42 /// Any endpoint that speaks Anthropic's Messages API: the workspace's
43 /// own Cloudflare AI Gateway, LiteLLM, a proxy in front of Bedrock or
44 /// Vertex, or a self-hosted model.
45 AnthropicEndpoint,
46 /// Any endpoint that speaks OpenAI's Chat Completions API: vLLM,
47 /// Ollama behind a tunnel, LiteLLM, a gateway.
48 OpenaiEndpoint,
49 // Alerts.
50 Sentry,
51 Datadog,
52 /// Anything that can send a signed JSON request.
53 Webhook,
54 // Trackers.
55 Jira,
56 Linear,
57}
58
59/// What g1t knows about a provider.
60pub struct Spec {
61 pub provider: Provider,
62 pub name: &'static str,
63 pub label: &'static str,
64 pub kind: ProviderKind,
65 /// For a model provider: the API it speaks, `anthropic` or `openai`.
66 pub api: &'static str,
67 /// For a model provider with a fixed address: where its API is, with
68 /// the version for OpenAI's API and without it for Anthropic's. Empty
69 /// when the connection gives its own.
70 pub base_url: &'static str,
71 /// The header the key goes in; `authorization` means `Bearer <key>`.
72 pub auth_header: &'static str,
73}
74
75const fn model(provider: Provider, name: &'static str, label: &'static str, api: &'static str, base_url: &'static str, auth_header: &'static str) -> Spec {
76 Spec {
77 provider,
78 name,
79 label,
80 kind: ProviderKind::Models,
81 api,
82 base_url,
83 auth_header,
84 }
85}
86
87const fn other(provider: Provider, name: &'static str, label: &'static str, kind: ProviderKind) -> Spec {
88 Spec {
89 provider,
90 name,
91 label,
92 kind,
93 api: "",
94 base_url: "",
95 auth_header: "",
96 }
97}
98
99/// Every provider, in the order people are shown them.
100pub const PROVIDERS: [Spec; 19] = [
101 model(Provider::Anthropic, "anthropic", "Anthropic", "anthropic", "https://api.anthropic.com", "x-api-key"),
102 model(Provider::Openai, "openai", "OpenAI", "openai", "https://api.openai.com/v1", "authorization"),
103 model(Provider::Gemini, "gemini", "Google Gemini", "openai", "https://generativelanguage.googleapis.com/v1beta/openai", "authorization"),
104 model(Provider::Xai, "xai", "xAI", "openai", "https://api.x.ai/v1", "authorization"),
105 model(Provider::Mistral, "mistral", "Mistral", "openai", "https://api.mistral.ai/v1", "authorization"),
106 model(Provider::Deepseek, "deepseek", "DeepSeek", "openai", "https://api.deepseek.com/v1", "authorization"),
107 model(Provider::AzureOpenai, "azure_openai", "Azure OpenAI", "openai", "", "api-key"),
108 model(Provider::Openrouter, "openrouter", "OpenRouter", "openai", "https://openrouter.ai/api/v1", "authorization"),
109 model(Provider::Groq, "groq", "Groq", "openai", "https://api.groq.com/openai/v1", "authorization"),
110 model(Provider::Together, "together", "Together AI", "openai", "https://api.together.xyz/v1", "authorization"),
111 model(Provider::Fireworks, "fireworks", "Fireworks AI", "openai", "https://api.fireworks.ai/inference/v1", "authorization"),
112 model(Provider::Cerebras, "cerebras", "Cerebras", "openai", "https://api.cerebras.ai/v1", "authorization"),
113 model(Provider::AnthropicEndpoint, "anthropic_endpoint", "Anthropic-compatible endpoint", "anthropic", "", "x-api-key"),
114 model(Provider::OpenaiEndpoint, "openai_endpoint", "OpenAI-compatible endpoint", "openai", "", "authorization"),
115 other(Provider::Sentry, "sentry", "Sentry", ProviderKind::Alerts),
116 other(Provider::Datadog, "datadog", "Datadog", ProviderKind::Alerts),
117 other(Provider::Webhook, "webhook", "Webhook", ProviderKind::Alerts),
118 other(Provider::Jira, "jira", "Jira", ProviderKind::Tracker),
119 other(Provider::Linear, "linear", "Linear", ProviderKind::Tracker),
120];
121
122impl Provider {
123 pub fn spec(self) -> &'static Spec {
124 PROVIDERS
125 .iter()
126 .find(|spec| spec.provider == self)
127 .expect("every provider is in the catalogue")
128 }
129
130 pub fn all() -> impl Iterator<Item = Provider> {
131 PROVIDERS.iter().map(|spec| spec.provider)
132 }
133
134 pub fn name(self) -> &'static str {
135 self.spec().name
136 }
137
138 pub fn parse(name: &str) -> Option<Provider> {
139 PROVIDERS.iter().find(|spec| spec.name == name).map(|spec| spec.provider)
140 }
141
142 /// What people call it.
143 pub fn label(self) -> &'static str {
144 self.spec().label
145 }
146
147 pub fn kind(self) -> ProviderKind {
148 self.spec().kind
149 }
150
151 /// Whether it sends g1t requests, at the connection's own address.
152 pub fn receives(self) -> bool {
153 self.kind() == ProviderKind::Alerts
154 }
155
156 /// For a model provider, the API it speaks: `anthropic` or `openai`.
157 pub fn api(self) -> &'static str {
158 self.spec().api
159 }
160
161 /// Whether the connection gives the address, rather than g1t knowing it.
162 pub fn own_address(self) -> bool {
163 self.kind() == ProviderKind::Models && self.spec().base_url.is_empty()
164 }
165}
166
167#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
168#[serde(rename_all = "snake_case")]
169pub enum ProviderKind {
170 /// An AI provider whose credentials the workspace keeps.
171 Models,
172 /// Problems that become issues.
173 Alerts,
174 /// Tickets that people read and import.
175 Tracker,
176}
177
178/// A connection's settings: everything about it except its secrets. Each
179/// provider uses the fields that apply to it.
180#[derive(Clone, Debug, Serialize, Deserialize)]
181#[serde(rename_all = "camelCase")]
182pub struct ConnectionConfig {
183 /// For alerts: the repository issues are opened in, `owner/name`. For a
184 /// tracker: where an imported ticket goes when no repository is named.
185 #[serde(default, skip_serializing_if = "Option::is_none")]
186 pub repo: Option<String>,
187 /// For alerts: the label put on each issue opened. `bug` when unset.
188 #[serde(default, skip_serializing_if = "Option::is_none")]
189 pub label: Option<String>,
190 /// Tell the outside system when the work lands: resolve the Sentry
191 /// issue, comment on the ticket.
192 #[serde(default = "yes")]
193 pub write_back: bool,
194 /// Sentry: the organization's slug.
195 #[serde(default, skip_serializing_if = "Option::is_none")]
196 pub organization: Option<String>,
197 /// The system's address, for Jira (`https://acme.atlassian.net`) or a
198 /// Sentry that is not sentry.io.
199 #[serde(default, skip_serializing_if = "Option::is_none")]
200 pub site: Option<String>,
201 /// Jira: the account the API token belongs to.
202 #[serde(default, skip_serializing_if = "Option::is_none")]
203 pub email: Option<String>,
204 /// Jira project keys or Linear team keys this connection answers for,
205 /// such as `TECH`. Empty answers for every key.
206 #[serde(default, skip_serializing_if = "Vec::is_empty")]
207 pub keys: Vec<String>,
208 /// Your own endpoint: its base URL, without `/v1`.
209 #[serde(default, skip_serializing_if = "Option::is_none")]
210 pub base_url: Option<String>,
211 /// Your own endpoint: send the key as `x-api-key` (the default) or as
212 /// `authorization: Bearer`.
213 #[serde(default, skip_serializing_if = "Option::is_none")]
214 pub auth_header: Option<String>,
215 /// For an AI provider: the model the team uses on it, when it names one.
216 #[serde(default, skip_serializing_if = "Option::is_none")]
217 pub model: Option<String>,
218}
219
220fn yes() -> bool {
221 true
222}
223
224impl Default for ConnectionConfig {
225 fn default() -> Self {
226 ConnectionConfig {
227 repo: None,
228 label: None,
229 write_back: true,
230 organization: None,
231 site: None,
232 email: None,
233 keys: Vec::new(),
234 base_url: None,
235 auth_header: None,
236 model: None,
237 }
238 }
239}
240
241/// A connection, as anyone in the workspace sees it. Secrets are never
242/// shown after they are saved; `secretHint` is enough to tell keys apart.
243#[derive(Clone, Debug, Serialize, Deserialize)]
244#[serde(rename_all = "camelCase")]
245pub struct Connection {
246 pub id: String,
247 pub workspace: String,
248 pub provider: Provider,
249 pub kind: ProviderKind,
250 pub name: String,
251 pub config: ConnectionConfig,
252 /// The last four characters of the saved key, such as `…3f9a`.
253 pub secret_hint: Option<String>,
254 /// For a provider that sends g1t requests: where it sends them.
255 pub webhook_url: Option<String>,
256 pub created_by: String,
257 /// RFC 3339.
258 pub created_at: String,
259 pub last_used_at: Option<String>,
260 /// The last thing that went wrong talking to it, until it next works.
261 pub last_error: Option<String>,
262 /// For a model provider: the models it offered when last checked.
263 #[serde(default)]
264 pub models: Vec<String>,
265}
266
267/// One request an outside system sent, and what g1t did with it.
268#[derive(Clone, Debug, Serialize, Deserialize)]
269#[serde(rename_all = "camelCase")]
270pub struct Delivery {
271 pub id: String,
272 /// RFC 3339.
273 pub received_at: String,
274 /// What it was about, in the sender's terms: `issue.created`.
275 pub event: String,
276 /// `opened`, `updated`, `reopened`, `ignored` or `refused`.
277 pub outcome: String,
278 pub detail: String,
279 /// The issue it opened or updated, `owner/name#number`.
280 pub issue: Option<String>,
281}
282
283/// Something outside g1t, fetched as it is now. Its text was written outside
284/// g1t, so it is reference material and never instructions.
285#[derive(Clone, Debug, Serialize, Deserialize)]
286#[serde(rename_all = "camelCase")]
287pub struct ContextItem {
288 pub provider: Provider,
289 /// `TECH-1234`, or the Sentry issue's short id.
290 pub key: String,
291 pub title: String,
292 pub url: String,
293 /// Its status in that system: `In Progress`, `unresolved`.
294 pub status: Option<String>,
295 /// Its description, as plain text, shortened if long.
296 pub body: String,
297 /// RFC 3339: when g1t fetched it.
298 pub fetched_at: String,
299}
300
301/// An issue's tie to something outside g1t.
302#[derive(Clone, Debug, Serialize, Deserialize)]
303#[serde(rename_all = "camelCase")]
304pub struct Link {
305 pub provider: Provider,
306 pub connection_id: String,
307 pub key: String,
308 pub title: String,
309 pub url: String,
310 /// How many times an alert has fired for it.
311 pub count: u32,
312 /// RFC 3339.
313 pub first_seen: String,
314 pub last_seen: String,
315}
316
317// --- Methods -----------------------------------------------------------------
318
319/// `list`. Returns `Outcome<Vec<Connection>>`. Members only.
320#[derive(Debug, Serialize, Deserialize)]
321pub struct ListArgs {
322 pub workspace: String,
323 pub viewer: Viewer,
324}
325
326/// `connect`. Returns `Outcome<Connected>`. Owners only.
327#[derive(Debug, Serialize, Deserialize)]
328#[serde(rename_all = "camelCase")]
329pub struct ConnectArgs {
330 pub actor: User,
331 pub workspace: String,
332 pub provider: Provider,
333 #[serde(default)]
334 pub name: Option<String>,
335 #[serde(default)]
336 pub config: ConnectionConfig,
337 /// The API key or token g1t uses to call it.
338 #[serde(default)]
339 pub secret: Option<String>,
340 /// What it signs its requests to g1t with: Sentry's client secret.
341 /// Made by g1t for Datadog and webhooks, and shown once.
342 #[serde(default)]
343 pub signing_secret: Option<String>,
344}
345
346#[derive(Clone, Debug, Serialize, Deserialize)]
347#[serde(rename_all = "camelCase")]
348pub struct Connected {
349 pub connection: Connection,
350 /// A signing secret g1t made, shown this once.
351 pub signing_secret: Option<String>,
352}
353
354/// `update`: only the fields given change. Returns `Outcome<Connection>`.
355/// Owners only.
356#[derive(Debug, Serialize, Deserialize)]
357#[serde(rename_all = "camelCase")]
358pub struct UpdateArgs {
359 pub actor: User,
360 pub workspace: String,
361 pub id: String,
362 #[serde(default)]
363 pub name: Option<String>,
364 #[serde(default)]
365 pub config: Option<ConnectionConfig>,
366 #[serde(default)]
367 pub secret: Option<String>,
368 #[serde(default)]
369 pub signing_secret: Option<String>,
370}
371
372/// `disconnect` and `test`. `disconnect` returns `Outcome<bool>`; `test`
373/// returns `Outcome<Tested>`. Owners only.
374#[derive(Debug, Serialize, Deserialize)]
375pub struct ConnectionArgs {
376 pub actor: User,
377 pub workspace: String,
378 pub id: String,
379}
380
381#[derive(Clone, Debug, Serialize, Deserialize)]
382pub struct Tested {
383 pub ok: bool,
384 pub message: String,
385}
386
387/// `deliveries`: the latest requests a connection received, newest first.
388/// Returns `Outcome<Vec<Delivery>>`. Members only.
389#[derive(Debug, Serialize, Deserialize)]
390pub struct DeliveriesArgs {
391 pub workspace: String,
392 pub viewer: Viewer,
393 pub id: String,
394}
395
396/// `receive`: a request an outside system sent to a connection's address.
397/// Returns `Received`. Anyone can send one; only a signed one is acted on.
398#[derive(Debug, Serialize, Deserialize)]
399pub struct ReceiveArgs {
400 pub id: String,
401 /// Header names in lowercase.
402 pub headers: std::collections::HashMap<String, String>,
403 pub body: String,
404}
405
406#[derive(Clone, Debug, Serialize, Deserialize)]
407pub struct Received {
408 /// The HTTP status to answer with.
409 pub status: u16,
410 pub message: String,
411}
412
413/// `resolve`: fetches one outside reference. Returns `Outcome<ContextItem>`.
414/// Members of the workspace only.
415#[derive(Debug, Serialize, Deserialize)]
416pub struct ResolveArgs {
417 pub workspace: String,
418 pub viewer: Viewer,
419 /// `TECH-1234`, or a Jira, Linear or Sentry address.
420 pub reference: String,
421}
422
423/// `import`: opens an issue from a ticket. Returns `Outcome<Imported>`.
424#[derive(Debug, Serialize, Deserialize)]
425pub struct ImportArgs {
426 pub actor: User,
427 pub repo: RepoPath,
428 pub reference: String,
429}
430
431#[derive(Clone, Debug, Serialize, Deserialize)]
432pub struct Imported {
433 pub number: u32,
434 pub item: ContextItem,
435 /// False when the ticket had been imported already, and `number` is
436 /// that issue.
437 pub created: bool,
438}
439
440/// `links`: what an issue is tied to outside g1t. Returns `Vec<Link>`.
441/// Callers must have checked the viewer may see the issue.
442#[derive(Debug, Serialize, Deserialize)]
443#[serde(rename_all = "camelCase")]
444pub struct LinksArgs {
445 pub repo: RepoPath,
446 pub number: u32,
447}
448
449#[cfg(test)]
450mod tests {
451 use super::*;
452
453 #[test]
454 fn every_provider_is_named_once_and_found_again() {
455 let mut names: Vec<&str> = PROVIDERS.iter().map(|spec| spec.name).collect();
456 for provider in Provider::all() {
457 assert_eq!(Provider::parse(provider.name()), Some(provider));
458 }
459 names.sort();
460 names.dedup();
461 assert_eq!(names.len(), PROVIDERS.len());
462 }
463
464 #[test]
465 fn ai_providers_are_connections_like_any_other() {
466 assert_eq!(Provider::parse("anthropic"), Some(Provider::Anthropic));
467 let stored: Provider = serde_json::from_str("\"openai_endpoint\"").unwrap();
468 assert_eq!(stored.kind(), ProviderKind::Models);
469 assert!(stored.own_address());
470 assert!(!Provider::Anthropic.own_address());
471 assert!(Provider::all().any(|provider| provider == Provider::Groq));
472 assert!(Provider::all().any(|provider| provider == Provider::Sentry));
473 }
474
475 #[test]
476 fn stored_configs_with_old_fields_parse() {
477 let config: ConnectionConfig =
478 serde_json::from_str(r#"{"repo":"acme/web","assign":true,"gatewayModels":["*"],"writeBack":false}"#).unwrap();
479 assert_eq!(config.repo.as_deref(), Some("acme/web"));
480 assert!(!config.write_back);
481 }
482
483 #[test]
484 fn model_providers_say_how_to_reach_them() {
485 for spec in PROVIDERS.iter().filter(|spec| spec.kind == ProviderKind::Models) {
486 assert!(spec.api == "anthropic" || spec.api == "openai", "{}", spec.name);
487 assert!(!spec.auth_header.is_empty(), "{}", spec.name);
488 assert!(spec.base_url.is_empty() || spec.base_url.starts_with("https://"), "{}", spec.name);
489 }
490 }
491}