Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -431,7 +431,7 @@ brainpod describe resource app --json
brainpod describe resource postgres --json
```

Resource schemas are fetched on each request from `<endpoint>/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 `<endpoint>/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: `${<name>.uri}` becomes `${db.uri}` for a resource named `db`. Template-sourced variables also report the template, which contains references only and never values.

Expand Down
14 changes: 8 additions & 6 deletions src/main.rs
Original file line number Diff line number Diff line change
Expand Up @@ -105,12 +105,14 @@ async fn run(opts: Opts) -> Result<output::CommandOutput> {

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
Expand Down
37 changes: 26 additions & 11 deletions src/openapi.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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"];
Expand All @@ -19,9 +18,11 @@ pub fn is_resource_path(path: &[String]) -> bool {
}
}

pub async fn describe(path: &[String], endpoint: Option<&str>) -> Result<Value> {
/// 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<String>) -> Result<Value> {
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)?;

Expand Down Expand Up @@ -93,8 +94,11 @@ async fn fetch_spec(url: &str) -> Result<Value> {
.context("Brainpod OpenAPI specification is not valid JSON")
}

fn openapi_url(endpoint: Option<&str>) -> Result<String> {
if let Some(url) = std::env::var_os("BRAINPOD_OPENAPI_URL") {
fn openapi_url(
document_override: Option<std::ffi::OsString>,
endpoint: impl FnOnce() -> Result<String>,
) -> Result<String> {
if let Some(url) = document_override {
let url = url
.into_string()
.map_err(|_| anyhow!("BRAINPOD_OPENAPI_URL is not valid UTF-8"))?;
Expand All @@ -104,11 +108,7 @@ fn openapi_url(endpoint: Option<&str>) -> Result<String> {
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()
Expand Down Expand Up @@ -167,7 +167,7 @@ fn resource_schemas(spec: &Value) -> Result<Vec<ResourceCatalog>> {
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() {
Expand All @@ -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!({
Expand Down
Loading