use std::{collections::BTreeMap, fs};
use axum::{
extract::{Path, State},
http::StatusCode,
response::{IntoResponse, Response},
Json,
};
use serde::Deserialize;
use serde_json::Value;
use crate::AppState;
#[derive(Clone, Default)]
pub struct Catalog {
documents: BTreeMap<String, String>,
selections: BTreeMap<String, Value>,
}
#[derive(Deserialize)]
struct CatalogConfig {
platforms: Vec<PlatformConfig>,
}
#[derive(Deserialize)]
struct PlatformConfig {
name: String,
openapi: String,
#[serde(default)]
overlays: Vec<String>,
#[serde(default)]
selection: Option<serde_json::Map<String, Value>>,
}
#[derive(Deserialize)]
struct Overlay {
actions: Vec<Action>,
}
#[derive(Deserialize)]
struct Action {
target: String,
update: Value,
}
impl Catalog {
#[cfg(test)]
pub(crate) fn from_test_document(platform: &str, document: Value, selection: Value) -> Self {
Self {
documents: [(
platform.to_owned(),
serde_yaml::to_string(&document).expect("test document serializes"),
)]
.into(),
selections: [(platform.to_owned(), selection)].into(),
}
}
#[cfg(test)]
pub(crate) fn for_test(platform: &str) -> Self {
Self {
documents: [(platform.into(), serde_json::json!({
"components": {"securitySchemes": {"fixture": {"type": "oauth2", "flows": {
"authorizationCode": {"authorizationUrl": "https://auth.example/authorize",
"tokenUrl": "https://auth.example/token", "scopes": {"read": "Read records"}}
}}}}, "security": [{"fixture": ["read"]}], "paths": {"/records": {"get": {}}}
}).to_string())].into(),
..Self::default()
}
}
pub async fn load(path: &str, client: &reqwest::Client) -> Result<Self, String> {
Self::load_with_mirror(path, client, None).await
}
#[cfg(test)]
pub(crate) async fn load_checked_in(client: &reqwest::Client) -> Result<Self, String> {
let overlays = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("../overlays");
let catalog = overlays.join("catalog.json");
Self::load_with_mirror(&catalog.to_string_lossy(), client, Some(&overlays)).await
}
async fn load_with_mirror(
path: &str,
client: &reqwest::Client,
mirror: Option<&std::path::Path>,
) -> Result<Self, String> {
let source = if path.starts_with("https://") {
fetch_yaml(client, path).await?
} else {
fs::read_to_string(path).map_err(|err| format!("cannot read {path}: {err}"))?
};
let config = parse_catalog_config(&source, path)?;
let mut documents = BTreeMap::new();
let mut selections = BTreeMap::new();
for platform in config.platforms {
valid_platform_name(&platform.name)?;
let base = fetch_source(client, &platform.openapi, mirror).await?;
let mut document: Value = serde_yaml::from_str(&base)
.map_err(|err| format!("cannot parse OAD for {}: {err}", platform.name))?;
for overlay_url in platform.overlays {
let overlay: Overlay =
serde_yaml::from_str(&fetch_source(client, &overlay_url, mirror).await?)
.map_err(|err| {
format!("cannot parse overlay for {}: {err}", platform.name)
})?;
for action in overlay.actions {
merge_at_target(&mut document, &action.target, action.update)?;
}
}
if let Some(selection) = platform.selection {
selections.insert(platform.name.clone(), Value::Object(selection));
}
insert_document(
&mut documents,
&platform.name,
serde_yaml::to_string(&document).map_err(|err| err.to_string())?,
)?;
}
Ok(Self {
documents,
selections,
})
}
pub fn names(&self) -> Vec<String> {
self.documents.keys().cloned().collect()
}
pub fn allows(&self, platform: &str, method: &str, path: &str) -> Option<url::Url> {
let document: Value = serde_yaml::from_str(self.documents.get(platform)?).ok()?;
let server = document
.get("servers")?
.as_array()?
.first()?
.get("url")?
.as_str()?;
let server_url = url::Url::parse(server).ok()?;
let base_path = server_url.path().trim_end_matches('/');
let relative_path = path.strip_prefix(base_path)?;
if !relative_path.starts_with('/') {
return None;
}
let paths = document.get("paths")?.as_object()?;
let template = paths
.keys()
.find(|template| path_matches(template, relative_path))?;
if !paths
.get(template)?
.get(method.to_ascii_lowercase())?
.is_object()
{
return None;
}
Some(server_url)
}
pub fn required_headers(
&self,
platform: &str,
method: &str,
path: &str,
) -> Option<Vec<(String, String)>> {
let document: Value = serde_yaml::from_str(self.documents.get(platform)?).ok()?;
let server = document
.get("servers")?
.as_array()?
.first()?
.get("url")?
.as_str()?;
let server_url = url::Url::parse(server).ok()?;
let relative = path.strip_prefix(server_url.path().trim_end_matches('/'))?;
let paths = document.get("paths")?.as_object()?;
let template = paths.keys().find(|t| path_matches(t, relative))?;
let path_item = paths.get(template)?.as_object()?;
let operation = path_item.get(&method.to_ascii_lowercase())?.as_object()?;
let mut out = Vec::new();
let mut seen = std::collections::BTreeSet::new();
for parameter in operation
.get("parameters")
.into_iter()
.chain(path_item.get("parameters"))
.flat_map(Value::as_array)
.flatten()
{
let parameter = if let Some(reference) = parameter.get("$ref").and_then(Value::as_str) {
document.pointer(reference.strip_prefix('#')?)?
} else {
parameter
};
if parameter.get("in").and_then(Value::as_str) != Some("header") {
continue;
}
let name = parameter.get("name").and_then(Value::as_str)?;
if !seen.insert(name.to_ascii_lowercase()) {
continue;
}
if name.eq_ignore_ascii_case("authorization") || name.eq_ignore_ascii_case("host") {
return None;
}
let value = parameter
.get("schema")
.and_then(|s| s.get("default"))
.or_else(|| {
parameter
.get("schema")
.and_then(|s| s.get("enum"))
.and_then(|e| e.as_array())
.filter(|a| a.len() == 1)
.and_then(|a| a.first())
});
let Some(value) = value.and_then(Value::as_str) else {
if parameter.get("required").and_then(Value::as_bool) == Some(true) {
return None;
} else {
continue;
}
};
out.push((name.to_owned(), value.to_owned()));
}
Some(out)
}
pub fn validate_request(
&self,
platform: &str,
method: &str,
path: &str,
query: Option<&str>,
content_type: Option<&str>,
has_body: bool,
) -> Result<(), &'static str> {
let document: Value =
serde_yaml::from_str(self.documents.get(platform).ok_or("unknown platform")?)
.map_err(|_| "invalid catalog document")?;
let server = document
.get("servers")
.and_then(Value::as_array)
.and_then(|servers| servers.first())
.and_then(|server| server.get("url"))
.and_then(Value::as_str)
.ok_or("invalid catalog document")?;
let server_url = url::Url::parse(server).map_err(|_| "invalid catalog document")?;
let relative = path
.strip_prefix(server_url.path().trim_end_matches('/'))
.ok_or("method or path is not in the catalog")?;
let paths = document
.get("paths")
.and_then(Value::as_object)
.ok_or("invalid catalog document")?;
let template = paths
.keys()
.find(|t| path_matches(t, relative))
.ok_or("method or path is not in the catalog")?;
let path_item = paths
.get(template)
.and_then(Value::as_object)
.ok_or("invalid catalog document")?;
let operation = path_item
.get(&method.to_ascii_lowercase())
.and_then(Value::as_object)
.ok_or("method or path is not in the catalog")?;
let query_pairs: Vec<(String, String)> = query
.map(|q| {
url::form_urlencoded::parse(q.as_bytes())
.into_owned()
.collect()
})
.unwrap_or_default();
for parameter in operation
.get("parameters")
.into_iter()
.chain(path_item.get("parameters"))
.flat_map(Value::as_array)
.flatten()
{
let parameter = if let Some(reference) = parameter.get("$ref").and_then(Value::as_str) {
document
.pointer(
reference
.strip_prefix('#')
.ok_or("invalid catalog document")?,
)
.ok_or("invalid catalog document")?
} else {
parameter
};
if parameter.get("in").and_then(Value::as_str) != Some("query") {
continue;
}
let name = parameter
.get("name")
.and_then(Value::as_str)
.ok_or("invalid catalog document")?;
let values: Vec<&str> = query_pairs
.iter()
.filter(|(key, _)| key == name)
.map(|(_, value)| value.as_str())
.collect();
if values.is_empty() {
if parameter.get("required").and_then(Value::as_bool) == Some(true) {
return Err("missing required query parameter");
}
continue;
}
if let Some(allowed) = parameter
.get("schema")
.and_then(|schema| schema.get("enum"))
.and_then(Value::as_array)
{
let allowed: Vec<&str> = allowed.iter().filter_map(Value::as_str).collect();
if values.iter().any(|value| !allowed.contains(value)) {
return Err("query parameter value is not permitted");
}
}
}
match operation.get("requestBody") {
None => {
if has_body {
return Err("operation does not accept a request body");
}
}
Some(request_body) => {
if !has_body {
if request_body.get("required").and_then(Value::as_bool) == Some(true) {
return Err("operation requires a request body");
}
return Ok(());
}
let content = request_body
.get("content")
.and_then(Value::as_object)
.ok_or("invalid catalog document")?;
let media_type = content_type
.and_then(|value| value.split(';').next())
.map(str::trim)
.unwrap_or("");
if !content.contains_key(media_type) {
return Err("unsupported content type");
}
}
}
Ok(())
}
pub fn oauth_provider(&self, platform: &str) -> Result<crate::providers::Provider, String> {
let source = self.get(platform).ok_or("unknown catalog platform")?;
let document = serde_yaml::from_str(source).map_err(|_| "invalid catalog document")?;
let scheme = match self
.selections
.get(platform)
.and_then(|selection| selection.get("oauthSecurityScheme"))
{
Some(Value::String(scheme)) => Some(scheme.as_str()),
Some(_) => return Err("oauthSecurityScheme selection must be a string".into()),
None => None,
};
crate::providers::Provider::from_document(&document, scheme)
}
pub fn security_scheme(
&self,
platform: &str,
) -> Result<crate::providers::SecurityScheme, String> {
let source = self.get(platform).ok_or("unknown catalog platform")?;
let document = serde_yaml::from_str(source).map_err(|_| "invalid catalog document")?;
let selection = self.selections.get(platform);
let read_selected = |key: &str| -> Result<Option<&str>, String> {
match selection.and_then(|selection| selection.get(key)) {
Some(Value::String(scheme)) => Ok(Some(scheme.as_str())),
Some(_) => Err(format!("{key} selection must be a string")),
None => Ok(None),
}
};
let oauth_scheme = read_selected("oauthSecurityScheme")?;
let api_key_scheme = read_selected("apiKeySecurityScheme")?;
crate::providers::SecurityScheme::from_document(&document, oauth_scheme, api_key_scheme)
}
fn get(&self, platform: &str) -> Option<&str> {
self.documents.get(platform).map(String::as_str)
}
}
fn parse_catalog_config(source: &str, path: &str) -> Result<CatalogConfig, String> {
serde_yaml::from_str(source).map_err(|err| format!("cannot parse {path}: {err}"))
}
fn insert_document(
documents: &mut BTreeMap<String, String>,
name: &str,
document: String,
) -> Result<(), String> {
if documents.insert(name.to_string(), document).is_some() {
return Err(format!("duplicate platform name {name:?}"));
}
Ok(())
}
fn path_matches(template: &str, path: &str) -> bool {
let left: Vec<_> = template.trim_matches('/').split('/').collect();
let right: Vec<_> = path.trim_matches('/').split('/').collect();
left.len() == right.len()
&& left
.iter()
.zip(right)
.all(|(template, path)| path_segment_matches(template, path))
}
fn path_segment_matches(template: &str, path: &str) -> bool {
let Some(open) = template.find('{') else {
return template == path;
};
let Some(close) = template[open + 1..].find('}') else {
return false;
};
let close = open + 1 + close;
if template[close + 1..].contains(['{', '}'])
|| template[..open].contains('}')
|| template[open + 1..close].contains('{')
|| template[open + 1..close].is_empty()
{
return false;
}
let prefix = &template[..open];
let suffix = &template[close + 1..];
path.starts_with(prefix)
&& path.ends_with(suffix)
&& path.len() >= prefix.len() + suffix.len()
&& !path[prefix.len()..path.len() - suffix.len()].is_empty()
}
async fn fetch_source(
client: &reqwest::Client,
url: &str,
mirror: Option<&std::path::Path>,
) -> Result<String, String> {
match (mirror, url.strip_prefix(crate::config::OVERLAYS_PAGES_BASE)) {
(Some(dir), Some(relative)) => {
let file = dir.join(relative);
fs::read_to_string(&file)
.map_err(|err| format!("cannot read {}: {err}", file.display()))
}
_ => fetch_yaml(client, url).await,
}
}
async fn fetch_yaml(client: &reqwest::Client, url: &str) -> Result<String, String> {
let url = url::Url::parse(url).map_err(|err| format!("invalid catalog URL: {err}"))?;
if url.scheme() != "https" {
return Err("catalog sources must use HTTPS".to_string());
}
client
.get(url)
.send()
.await
.map_err(|err| err.to_string())?
.error_for_status()
.map_err(|err| err.to_string())?
.text()
.await
.map_err(|err| err.to_string())
}
fn valid_platform_name(name: &str) -> Result<(), String> {
if !name.is_empty()
&& name
.bytes()
.all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b == b'-')
{
Ok(())
} else {
Err(format!("invalid platform name {name:?}"))
}
}
fn merge_at_target(document: &mut Value, target: &str, update: Value) -> Result<(), String> {
let keys = parse_target(target)?;
let mut current = document;
for key in keys {
current = current
.get_mut(&key)
.ok_or_else(|| format!("overlay target {target:?} does not exist"))?;
}
merge(current, update);
Ok(())
}
fn parse_target(target: &str) -> Result<Vec<String>, String> {
let mut rest = target
.strip_prefix('$')
.ok_or_else(|| format!("unsupported overlay target {target:?}"))?;
let mut keys = Vec::new();
while !rest.is_empty() {
if let Some(after) = rest.strip_prefix('.') {
let end = after.find(['.', '[']).unwrap_or(after.len());
if end == 0 {
return Err(format!("unsupported overlay target {target:?}"));
}
keys.push(after[..end].to_string());
rest = &after[end..];
} else if let Some(after) = rest.strip_prefix("['") {
let end = after
.find("']")
.ok_or_else(|| format!("unsupported overlay target {target:?}"))?;
keys.push(after[..end].to_string());
rest = &after[end + 2..];
} else {
return Err(format!("unsupported overlay target {target:?}"));
}
}
Ok(keys)
}
fn merge(destination: &mut Value, update: Value) {
match (destination, update) {
(Value::Object(destination), Value::Object(update)) => {
for (key, value) in update {
merge(destination.entry(key).or_insert(Value::Null), value);
}
}
(destination, update) => *destination = update,
}
}
pub async fn list(State(state): State<AppState>) -> Json<Vec<String>> {
Json(state.catalog.names())
}
pub async fn document(Path(file): Path<String>, State(state): State<AppState>) -> Response {
if let Some(platform) = file.strip_suffix(".selection.json") {
if state.catalog.get(platform).is_none() {
return (StatusCode::NOT_FOUND, "catalog platform not found").into_response();
}
return Json(
state
.catalog
.selections
.get(platform)
.cloned()
.unwrap_or_else(|| serde_json::json!({})),
)
.into_response();
}
let Some(platform) = file.strip_suffix(".yaml") else {
return (StatusCode::NOT_FOUND, "catalog platform not found").into_response();
};
match state.catalog.get(platform) {
Some(document) => (
[("content-type", "application/yaml; charset=utf-8")],
document.to_owned(),
)
.into_response(),
None => (StatusCode::NOT_FOUND, "catalog platform not found").into_response(),
}
}
#[cfg(test)]
mod tests {
#[test]
fn fixed_header_defaults_are_explicit_and_operation_overrides_path() {
use serde_json::json;
let mut doc = json!({"servers":[{"url":"https://example.com/v1"}], "paths":{"/items": {
"parameters":[{"in":"header","name":"X-Version","required":true,"schema":{"default":"old"}}],
"get":{"parameters":[
{"in":"header","name":"X-Version","required":true,"schema":{"enum":["new"]}},
{"in":"header","name":"X-Optional","example":"not a default","schema":{"type":"string"}}
]}
}}});
let headers = |doc: &serde_json::Value| {
let catalog = super::Catalog {
documents: [("test".into(), serde_yaml::to_string(doc).unwrap())].into(),
..Default::default()
};
catalog.required_headers("test", "GET", "/v1/items")
};
assert_eq!(
headers(&doc).unwrap(),
vec![("X-Version".into(), "new".into())]
);
doc["paths"]["/items"]["get"]["parameters"][1]["required"] = json!(true);
assert!(headers(&doc).is_none());
doc["paths"]["/items"]["get"]["parameters"][1]["schema"]["enum"] = json!(["one", "two"]);
assert!(headers(&doc).is_none());
doc["paths"]["/items"]["get"]["parameters"][1]["schema"]["default"] = json!("one");
assert_eq!(headers(&doc).unwrap().len(), 2);
}
#[test]
fn composed_clockify_fixture_declares_an_api_key_scheme_and_pagination() {
let document: Value =
serde_yaml::from_str(include_str!("../tests/fixtures/clockify-composed.yaml")).unwrap();
let catalog = Catalog::from_test_document("clockify", document, serde_json::json!({}));
let scheme = catalog.security_scheme("clockify").unwrap();
match scheme {
crate::providers::SecurityScheme::ApiKey(scheme) => {
assert_eq!(scheme.name, "X-Api-Key");
assert_eq!(scheme.location, crate::providers::ApiKeyLocation::Header);
}
crate::providers::SecurityScheme::OAuth(_) => panic!("expected an apiKey scheme"),
}
assert!(catalog
.allows(
"clockify",
"GET",
"/api/v1/workspaces/ws1/user/u1/time-entries"
)
.is_some());
assert_eq!(
catalog
.required_headers(
"clockify",
"GET",
"/api/v1/workspaces/ws1/user/u1/time-entries"
)
.unwrap(),
Vec::<(String, String)>::new()
);
}
#[test]
fn validate_request_checks_required_query_parameters_enums_and_body() {
use serde_json::json;
let doc = json!({"servers":[{"url":"https://example.com/v1"}], "paths":{"/items": {
"get":{"parameters":[
{"in":"query","name":"state","required":true,"schema":{"enum":["open","closed"]}},
{"in":"query","name":"page","schema":{"type":"integer"}}
]},
"post": {"requestBody": {"required": true, "content": {"application/json": {}}}}
}}});
let catalog = super::Catalog {
documents: [("test".into(), serde_yaml::to_string(&doc).unwrap())].into(),
..Default::default()
};
assert!(catalog
.validate_request("test", "GET", "/v1/items", None, None, false)
.is_err());
assert!(catalog
.validate_request(
"test",
"GET",
"/v1/items",
Some("state=pending"),
None,
false
)
.is_err());
assert!(catalog
.validate_request(
"test",
"GET",
"/v1/items",
Some("state=open&page=2&undeclared=1"),
None,
false
)
.is_ok());
assert!(catalog
.validate_request(
"test",
"GET",
"/v1/items",
Some("state=open"),
Some("application/json"),
true
)
.is_err());
assert!(catalog
.validate_request("test", "POST", "/v1/items", None, None, false)
.is_err());
assert!(catalog
.validate_request("test", "POST", "/v1/items", None, Some("text/plain"), true)
.is_err());
assert!(catalog
.validate_request(
"test",
"POST",
"/v1/items",
None,
Some("application/json; charset=utf-8"),
true
)
.is_ok());
assert!(catalog
.validate_request("test", "DELETE", "/v1/items", None, None, false)
.is_err());
}
#[test]
fn composed_notion_preserves_base_path_and_resolves_version_header() {
let catalog = super::Catalog {
documents: [(
"notion".into(),
include_str!("../tests/fixtures/notion-composed.yaml").into(),
)]
.into(),
..Default::default()
};
assert!(catalog.allows("notion", "POST", "/search").is_none());
assert!(catalog.allows("notion", "POST", "/v1/search").is_some());
assert_eq!(
catalog
.required_headers("notion", "POST", "/v1/search")
.unwrap(),
vec![("Notion-Version".into(), "2026-03-11".into())]
);
}
use super::*;
#[test]
fn default_catalog_is_the_published_checked_in_catalog() {
use crate::config::{DEFAULT_CATALOG_PATH, OVERLAYS_PAGES_BASE};
assert_eq!(
DEFAULT_CATALOG_PATH,
format!("{OVERLAYS_PAGES_BASE}catalog.json")
);
let overlays = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("../overlays");
let config = parse_catalog_config(
&fs::read_to_string(overlays.join("catalog.json")).unwrap(),
"catalog.json",
)
.unwrap();
for platform in config.platforms {
for url in platform.overlays {
let relative = url.strip_prefix(OVERLAYS_PAGES_BASE).unwrap_or_else(|| {
panic!("{}: {url} is not published from overlays/", platform.name)
});
assert!(
overlays.join(relative).is_file(),
"{}: missing overlays/{relative}",
platform.name
);
}
}
}
#[tokio::test]
#[ignore = "downloads the pinned OAD sources the default catalog composes"]
async fn default_catalog_pin_selects_google_offline_and_spotify_pkce_profiles() {
let catalog = Catalog::load_checked_in(&crate::build_http_client())
.await
.unwrap();
for name in catalog.names() {
let scheme = catalog
.security_scheme(&name)
.unwrap_or_else(|error| panic!("{name}: {error}"));
if let crate::providers::SecurityScheme::OAuth(provider) = scheme {
if name != "notion" {
assert!(!provider.scopes.is_empty(), "{name}");
}
}
}
let google = catalog.oauth_provider("google-calendar").unwrap();
assert!(google.use_pkce);
assert!(google
.authorization_params
.contains(&("access_type".into(), "offline".into())));
let spotify = catalog.oauth_provider("spotify").unwrap();
assert!(spotify.use_pkce);
assert!(catalog
.allows("github-issues", "GET", "/repositories/123/issues")
.is_some());
assert!(catalog
.allows(
"google-calendar",
"PATCH",
"/calendar/v3/calendars/team%40example.com/events/id"
)
.is_some());
}
#[tokio::test]
#[ignore = "downloads the pinned production catalog sources"]
async fn pinned_catalog_supplies_oauth_and_canonical_pagination_paths() {
let path = std::env::var("TEST_CATALOG_PATH").unwrap_or_else(|_| "https://raw.githubusercontent.com/localthought/overlays/d83c3ce0afd9f8ca0e4c42e142fa89d5fa9d8f70/catalog.json".into());
let catalog = Catalog::load(&path, &crate::build_http_client())
.await
.unwrap();
for name in catalog.names() {
let provider = catalog
.oauth_provider(&name)
.unwrap_or_else(|error| panic!("{name}: {error}"));
assert!(!provider.scopes.is_empty(), "{name}");
}
let moneybird: Value = serde_yaml::from_str(catalog.get("moneybird").unwrap()).unwrap();
let resources = moneybird
.pointer("/components/crudResources")
.unwrap()
.as_object()
.unwrap();
let collection_count: usize = resources
.values()
.filter_map(|r| r.get("collections").and_then(Value::as_object))
.map(|c| c.len())
.sum();
assert_eq!(collection_count, 32);
assert_eq!(
catalog.selections["moneybird"]["query_overrides"]
.as_array()
.unwrap()
.len(),
6
);
assert!(moneybird.get("selection").is_none());
assert_eq!(
moneybird.pointer("/x-throttling/limits/apiRequests/requests"),
Some(&serde_json::json!(150))
);
assert_eq!(
moneybird.pointer("/x-throttling/limits/apiRequests/window/kind"),
Some(&serde_json::json!("unspecified"))
);
assert!(catalog
.allows("github-issues", "GET", "/repositories/123/issues")
.is_some());
assert!(catalog
.allows(
"github-issues",
"GET",
"/repositories/123/issues/1/comments"
)
.is_some());
assert!(catalog
.allows("github-issues", "POST", "/repositories/123/issues")
.is_none());
}
#[tokio::test]
#[ignore = "downloads pinned OAuth authentication-details metadata"]
async fn pinned_catalog_selects_google_offline_and_spotify_pkce_profiles() {
let catalog = Catalog::load(
"https://raw.githubusercontent.com/localthought/overlays/d83c3ce0afd9f8ca0e4c42e142fa89d5fa9d8f70/catalog.json",
&crate::build_http_client(),
)
.await
.unwrap();
let google = catalog.oauth_provider("google-calendar").unwrap();
assert!(google.use_pkce);
assert!(google
.authorization_params
.contains(&("access_type".into(), "offline".into())));
let spotify = catalog.oauth_provider("spotify").unwrap();
assert!(spotify.use_pkce);
}
#[tokio::test]
#[ignore = "downloads the pinned production catalog sources"]
async fn pinned_todoist_catalog_is_read_only_and_preserves_api_prefix() {
let catalog = Catalog::load("https://raw.githubusercontent.com/localthought/overlays/a53b5e75641dabc04af18813348312edcd453bf9/catalog.json", &crate::build_http_client())
.await
.unwrap();
let document: Value = serde_yaml::from_str(catalog.get("todoist").unwrap()).unwrap();
let resources = document
.pointer("/components/crudResources")
.unwrap()
.as_object()
.unwrap();
assert_eq!(resources.len(), 2);
for resource in resources.values() {
let reference = resource.pointer("/schema/$ref").unwrap().as_str().unwrap();
assert!(document
.pointer(reference.strip_prefix('#').unwrap())
.is_some());
}
for path in [
"/api/v1/projects",
"/api/v1/tasks",
"/api/v1/projects/example",
"/api/v1/tasks/example",
] {
assert_eq!(
catalog.allows("todoist", "GET", path).unwrap().as_str(),
"https://api.todoist.com/api/v1"
);
for method in ["POST", "PUT", "PATCH", "DELETE"] {
assert!(catalog.allows("todoist", method, path).is_none());
}
}
for path in ["/tasks", "/api/v10/tasks", "/api/v1/access_tokens"] {
assert!(catalog.allows("todoist", "GET", path).is_none());
}
}
#[tokio::test]
#[ignore = "downloads the pinned production catalog sources"]
async fn pinned_discord_catalog_composes_and_allows_only_user_reads() {
let catalog = Catalog::load("https://raw.githubusercontent.com/localthought/overlays/a53b5e75641dabc04af18813348312edcd453bf9/catalog.json", &crate::build_http_client())
.await
.unwrap();
let document: Value = serde_yaml::from_str(catalog.get("discord").unwrap()).unwrap();
assert!(document
.pointer("/components/crudResources/guild")
.is_some());
for path in ["/api/v10/users/@me", "/api/v10/users/@me/guilds"] {
assert_eq!(
catalog.allows("discord", "GET", path).unwrap().as_str(),
"https://discord.com/api/v10"
);
assert!(catalog.allows("discord", "POST", path).is_none());
}
assert!(catalog
.allows("discord", "GET", "/api/v10/channels/123/messages")
.is_none());
assert!(catalog
.allows("discord", "GET", "/users/@me/guilds")
.is_none());
}
#[test]
fn discord_only_allows_profile_and_membership_reads_with_api_prefix() {
let catalog = Catalog { documents: BTreeMap::from([("discord".into(),
"servers:\n - url: https://discord.com/api/v10\npaths:\n /users/@me:\n get: {}\n /users/@me/guilds:\n get: {}\n".into())]), ..Catalog::default() };
for path in ["/api/v10/users/@me", "/api/v10/users/@me/guilds"] {
assert_eq!(
catalog.allows("discord", "GET", path).unwrap().as_str(),
"https://discord.com/api/v10"
);
assert!(catalog.allows("discord", "POST", path).is_none());
assert!(catalog.allows("discord", "DELETE", path).is_none());
}
for path in [
"/users/@me",
"/api/v100/users/@me",
"/api/v10/users/123",
"/api/v10/channels/123/messages",
] {
assert!(catalog.allows("discord", "GET", path).is_none());
}
}
#[test]
fn matches_moneybird_parameterized_contact_paths() {
let template = "/{administration_id}/contacts/{id}.json";
assert!(path_matches(template, "/123/contacts/456.json"));
assert!(!path_matches(template, "/123/contacts/.json"));
assert!(!path_matches(template, "/123/contacts/456.xml"));
assert!(!path_matches(template, "/123/invoices/456.json"));
}
#[test]
fn rejects_malformed_or_ambiguous_path_variables() {
assert!(!path_matches("/{id", "/123"));
assert!(!path_matches("/{{id}", "/123"));
assert!(!path_matches("/{id}/{other}{third}", "/123/456789"));
assert!(!path_matches("/{id}/contacts", "//contacts"));
}
#[tokio::test]
#[ignore = "downloads the pinned production catalog sources"]
async fn pinned_moneybird_catalog_composes_and_allows_contacts() {
let catalog = Catalog::load("https://raw.githubusercontent.com/localthought/overlays/a53b5e75641dabc04af18813348312edcd453bf9/catalog.json", &crate::build_http_client())
.await
.unwrap();
assert!(catalog.names().contains(&"moneybird".to_string()));
let document: Value = serde_yaml::from_str(catalog.get("moneybird").unwrap()).unwrap();
assert!(document
.pointer("/components/crudResources/contact/collections/contacts")
.is_some());
let schema_ref = document
.pointer("/components/crudResources/contact/schema/$ref")
.and_then(Value::as_str)
.expect("contacts must declare their schema");
let schema = document
.pointer(schema_ref.strip_prefix('#').unwrap())
.expect("contacts schema reference must resolve");
assert!(schema.pointer("/properties/company_name").is_some());
let upstream = catalog
.allows("moneybird", "GET", "/api/v2/123/contacts.json")
.expect("Moneybird contacts path must include the server base path");
assert_eq!(upstream.as_str(), "https://moneybird.com/api/v2");
assert!(catalog
.allows("moneybird", "GET", "/api/v2/123/contacts/456.json")
.is_some());
assert!(catalog
.allows("moneybird", "POST", "/api/v2/123/contacts.json")
.is_none());
assert!(catalog
.allows("moneybird", "GET", "/123/contacts.json")
.is_none());
assert!(catalog
.allows("moneybird", "GET", "/api/v20/123/contacts.json")
.is_none());
}
#[tokio::test]
#[ignore = "downloads the pinned production catalog sources"]
async fn pinned_spotify_catalog_composes_and_allows_readonly_playlists() {
let catalog = Catalog::load("https://raw.githubusercontent.com/localthought/overlays/a53b5e75641dabc04af18813348312edcd453bf9/catalog.json", &crate::build_http_client())
.await
.unwrap();
let document: Value = serde_yaml::from_str(catalog.get("spotify").unwrap()).unwrap();
assert!(document
.pointer("/components/crudResources")
.unwrap()
.as_object()
.is_some_and(|resources| !resources.is_empty()));
assert_eq!(
catalog
.allows("spotify", "GET", "/v1/me/playlists")
.unwrap()
.as_str(),
"https://api.spotify.com/v1"
);
assert!(catalog
.allows("spotify", "POST", "/v1/me/playlists")
.is_none());
assert!(catalog.allows("spotify", "GET", "/me/playlists").is_none());
assert!(catalog.allows("spotify", "GET", "/v1/me/tracks").is_none());
}
#[test]
fn validates_google_endpoints_relative_to_server_base_path() {
for server in [
"https://www.googleapis.com/calendar/v3",
"https://www.googleapis.com/calendar/v3/",
] {
let catalog = Catalog { documents: BTreeMap::from([("google-calendar".into(), format!("servers:\n - url: {server}\npaths:\n /users/me/calendarList:\n get: {{}}\n /calendars/{{calendarId}}/events:\n get: {{}}\n"))]), ..Catalog::default() };
assert!(catalog
.allows(
"google-calendar",
"GET",
"/calendar/v3/users/me/calendarList"
)
.is_some());
assert!(catalog
.allows(
"google-calendar",
"GET",
"/calendar/v3/calendars/a%40example.com/events"
)
.is_some());
assert!(catalog
.allows("google-calendar", "GET", "/users/me/calendarList")
.is_none());
assert!(catalog
.allows(
"google-calendar",
"GET",
"/calendar/v30/users/me/calendarList"
)
.is_none());
assert!(catalog
.allows(
"google-calendar",
"POST",
"/calendar/v3/users/me/calendarList"
)
.is_none());
}
}
use axum::{
body::{to_bytes, Body},
http::Request,
};
use tower::ServiceExt;
fn test_router() -> axum::Router {
let config: CatalogConfig = serde_yaml::from_str(
"platforms:\n - { name: github-issues, openapi: https://example.com/github.yaml }\n - { name: google-calendar, openapi: https://example.com/google.yaml }\n - { name: moneybird, openapi: https://example.com/moneybird.yaml }\n - { name: todoist, openapi: https://example.com/todoist.yaml }\n - { name: spotify, openapi: https://example.com/spotify.yaml }\n - { name: discord, openapi: https://example.com/discord.yaml }\n",
)
.unwrap();
let documents = config
.platforms
.into_iter()
.map(|platform| {
(
platform.name,
"openapi: 3.0.0\ninfo: {title: Test, version: '1'}\npaths: {}\n".to_string(),
)
})
.collect();
let mut state = crate::test_support::state(None);
state.base_url = "http://localhost".into();
state.catalog = Catalog { documents, selections: [("moneybird".into(), serde_json::json!({"query_overrides": [{"path":"/records", "values":{"include_archived":true}}]}))].into() };
crate::router(state)
}
#[tokio::test]
async fn router_serves_every_advertised_catalog_document() {
let app = test_router();
let response = app
.clone()
.oneshot(
Request::builder()
.uri("/catalog")
.body(Body::empty())
.unwrap(),
)
.await
.unwrap();
assert_eq!(response.status(), StatusCode::OK);
let names: Vec<String> =
serde_json::from_slice(&to_bytes(response.into_body(), usize::MAX).await.unwrap())
.unwrap();
assert!(!names.is_empty());
for name in names {
let response = app
.clone()
.oneshot(
Request::builder()
.uri(format!("/catalog/{name}.yaml"))
.body(Body::empty())
.unwrap(),
)
.await
.unwrap();
assert_eq!(response.status(), StatusCode::OK, "{name}");
let document: Value =
serde_yaml::from_slice(&to_bytes(response.into_body(), usize::MAX).await.unwrap())
.unwrap();
assert_eq!(document["openapi"], "3.0.0");
assert!(document["paths"].is_object());
}
for path in ["/catalog/unknown.yaml", "/catalog/github-issues.json"] {
let response = app
.clone()
.oneshot(Request::builder().uri(path).body(Body::empty()).unwrap())
.await
.unwrap();
assert_eq!(response.status(), StatusCode::NOT_FOUND);
}
}
#[tokio::test]
async fn consumer_selection_is_separate_from_api_metadata() {
let app = test_router();
for (name, expected) in [
(
"moneybird",
serde_json::json!({"query_overrides":[{"path":"/records","values":{"include_archived":true}}]}),
),
("github-issues", serde_json::json!({})),
] {
let response = app
.clone()
.oneshot(
Request::builder()
.uri(format!("/catalog/{name}.selection.json"))
.body(Body::empty())
.unwrap(),
)
.await
.unwrap();
assert_eq!(response.status(), StatusCode::OK);
let value: Value =
serde_json::from_slice(&to_bytes(response.into_body(), usize::MAX).await.unwrap())
.unwrap();
assert_eq!(value, expected);
let response = app
.clone()
.oneshot(
Request::builder()
.uri(format!("/catalog/{name}.yaml"))
.body(Body::empty())
.unwrap(),
)
.await
.unwrap();
let document: Value =
serde_yaml::from_slice(&to_bytes(response.into_body(), usize::MAX).await.unwrap())
.unwrap();
assert!(document.get("selection").is_none());
assert!(document.get("query_overrides").is_none());
}
let response = app
.oneshot(
Request::builder()
.uri("/catalog/unknown.selection.json")
.body(Body::empty())
.unwrap(),
)
.await
.unwrap();
assert_eq!(response.status(), StatusCode::NOT_FOUND);
assert!(parse_catalog_config(
r#"{"platforms":[{"name":"example","openapi":"https://example.com","selection":[]}]}"#,
"fixture"
)
.is_err());
}
#[test]
fn oauth_scheme_selection_rejects_non_string_values() {
let mut catalog = Catalog::for_test("fixture");
catalog.selections.insert(
"fixture".into(),
serde_json::json!({"oauthSecurityScheme": null}),
);
assert_eq!(
catalog.oauth_provider("fixture").unwrap_err(),
"oauthSecurityScheme selection must be a string"
);
}
#[tokio::test]
async fn router_reaches_parameterized_oauth_handlers() {
let app = test_router();
for provider in ["github-issues", "google-calendar", "moneybird", "discord"] {
for (action, query) in [("callback", "code=test&state=test")] {
let response = app
.clone()
.oneshot(
Request::builder()
.uri(format!("/oauth/{provider}/{action}?{query}"))
.body(Body::empty())
.unwrap(),
)
.await
.unwrap();
assert_eq!(
response.status(),
StatusCode::BAD_REQUEST,
"{provider}/{action}"
);
let body = to_bytes(response.into_body(), usize::MAX).await.unwrap();
assert_eq!(&body[..], b"OAuth request could not be completed");
}
}
}
#[test]
fn target_parser_supports_overlay_paths() {
assert_eq!(
parse_target("$.paths['/things/{id}'].get").unwrap(),
["paths", "/things/{id}", "get"]
);
}
#[test]
fn merge_preserves_existing_document_fields() {
let mut document = serde_json::json!({"components": {"schemas": {"old": true}}});
merge_at_target(
&mut document,
"$.components",
serde_json::json!({"securitySchemes": {"token": {"type": "http"}}}),
)
.unwrap();
assert_eq!(document["components"]["schemas"]["old"], true);
assert_eq!(
document["components"]["securitySchemes"]["token"]["type"],
"http"
);
}
#[test]
fn catalog_config_accepts_json_fixture_and_rejects_invalid_names() {
let config = parse_catalog_config(
r#"{"platforms":[{"name":"example","openapi":"https://example.com/oad.json"}]}"#,
"fixture.json",
)
.unwrap();
assert_eq!(config.platforms[0].name, "example");
assert!(valid_platform_name("bad_name").is_err());
}
#[test]
fn catalog_rejects_duplicate_platform_names() {
let mut documents = BTreeMap::new();
insert_document(&mut documents, "example", "{}".to_string()).unwrap();
assert_eq!(
insert_document(&mut documents, "example", "{}".to_string()).unwrap_err(),
"duplicate platform name \"example\""
);
}
}