diff --git a/README.md b/README.md index b00bfa6..238b40c 100644 --- a/README.md +++ b/README.md @@ -431,7 +431,7 @@ brainpod describe resource app --json brainpod describe resource postgres --json ``` -Resource schemas are fetched on each request from `/v1/openapi.json`, where the endpoint is resolved like every other command's: `--endpoint`, then `BRAINPOD_API_ENDPOINT`, then the configured endpoint, then `https://api.brainpod.io`. No API token is needed. If the document cannot be reached or does not contain the expected resource schemas, the version embedded in the CLI is used instead. Set `BRAINPOD_OPENAPI_URL` to override the document URL entirely. +Resource schemas are fetched on each request from `/v1/openapi.json`, where the endpoint is resolved like every other command's: `--endpoint`, then `BRAINPOD_API_ENDPOINT`, then the configured endpoint, then `https://api.brainpod.io`. No API token is needed. If the document cannot be reached or does not contain the expected resource schemas, the version embedded in the CLI is used instead. Set `BRAINPOD_OPENAPI_URL` to override the document URL entirely; the endpoint and configuration file are then not consulted. Each schema carries the variables that kind exports, so the references an App resource can use in `spec.env` are discoverable before the resource exists. Names in this catalog are placeholders: `${.uri}` becomes `${db.uri}` for a resource named `db`. Template-sourced variables also report the template, which contains references only and never values. diff --git a/src/main.rs b/src/main.rs index 86992a0..c174156 100644 --- a/src/main.rs +++ b/src/main.rs @@ -105,12 +105,14 @@ async fn run(opts: Opts) -> Result { if let Command::Describe(args) = &opts.command { if openapi::is_resource_path(&args.command) { - let endpoint = api_endpoint( - opts.endpoint.clone(), - environment("BRAINPOD_API_ENDPOINT"), - || Ok(Config::load(&Config::path()?)?.endpoint), - )?; - let resource_description = openapi::describe(&args.command, Some(&endpoint)).await?; + let resource_description = openapi::describe(&args.command, || { + api_endpoint( + opts.endpoint.clone(), + environment("BRAINPOD_API_ENDPOINT"), + || Ok(Config::load(&Config::path()?)?.endpoint), + ) + }) + .await?; if args.command.len() == 1 { let mut description = describe::generate(Opts::command(), &args.command)?; description diff --git a/src/openapi.rs b/src/openapi.rs index ae50121..894dccb 100644 --- a/src/openapi.rs +++ b/src/openapi.rs @@ -4,7 +4,6 @@ use anyhow::{Context, Result, anyhow}; use reqwest::Url; use serde_json::{Value, json}; -const PRODUCTION_OPENAPI_URL: &str = "https://api.brainpod.io/v1/openapi.json"; const EMBEDDED_OPENAPI: &str = include_str!("openapi.json"); const RESOURCE_SUBCOMMANDS: &[&str] = &["list", "get", "create", "replace", "delete", "variables"]; @@ -19,9 +18,11 @@ pub fn is_resource_path(path: &[String]) -> bool { } } -pub async fn describe(path: &[String], endpoint: Option<&str>) -> Result { +/// Describes resource schemas. `endpoint` resolves the API endpoint and is only called when +/// `BRAINPOD_OPENAPI_URL` does not override the document URL. +pub async fn describe(path: &[String], endpoint: impl FnOnce() -> Result) -> Result { let requested_kind = path.get(1).map(String::as_str); - let url = openapi_url(endpoint)?; + let url = openapi_url(std::env::var_os("BRAINPOD_OPENAPI_URL"), endpoint)?; let (spec, source) = load_spec(&url).await?; let resources = resource_schemas(&spec)?; @@ -93,8 +94,11 @@ async fn fetch_spec(url: &str) -> Result { .context("Brainpod OpenAPI specification is not valid JSON") } -fn openapi_url(endpoint: Option<&str>) -> Result { - if let Some(url) = std::env::var_os("BRAINPOD_OPENAPI_URL") { +fn openapi_url( + document_override: Option, + endpoint: impl FnOnce() -> Result, +) -> Result { + if let Some(url) = document_override { let url = url .into_string() .map_err(|_| anyhow!("BRAINPOD_OPENAPI_URL is not valid UTF-8"))?; @@ -104,11 +108,7 @@ fn openapi_url(endpoint: Option<&str>) -> Result { return Ok(url); } - let Some(endpoint) = endpoint else { - return Ok(PRODUCTION_OPENAPI_URL.to_owned()); - }; - - let mut url = Url::parse(endpoint).context("invalid Brainpod API endpoint")?; + let mut url = Url::parse(&endpoint()?).context("invalid Brainpod API endpoint")?; { let mut segments = url .path_segments_mut() @@ -167,7 +167,7 @@ fn resource_schemas(spec: &Value) -> Result> { mod tests { use serde_json::{Value, json}; - use super::{is_resource_path, resource_schemas}; + use super::{is_resource_path, openapi_url, resource_schemas}; #[test] fn recognizes_resource_schema_paths_without_shadowing_commands() { @@ -187,6 +187,21 @@ mod tests { ])); } + #[test] + fn openapi_url_override_skips_endpoint_resolution() { + assert_eq!( + openapi_url(Some("https://schema.example/openapi.json".into()), || { + panic!("endpoint must not be resolved") + }) + .unwrap(), + "https://schema.example/openapi.json" + ); + assert_eq!( + openapi_url(None, || Ok("https://api.example/".to_owned())).unwrap(), + "https://api.example/v1/openapi.json" + ); + } + #[test] fn extracts_resource_schemas_from_openapi() { let spec = json!({