diff --git a/.changeset/blue-dingos-repeat.md b/.changeset/blue-dingos-repeat.md new file mode 100644 index 0000000000..111a94a00b --- /dev/null +++ b/.changeset/blue-dingos-repeat.md @@ -0,0 +1,5 @@ +--- +'@backstage/plugin-auth-backend': patch +--- + +Require that audience URLs for Okta authentication start with https diff --git a/.changeset/eighty-forks-fry.md b/.changeset/eighty-forks-fry.md new file mode 100644 index 0000000000..4a25dd128a --- /dev/null +++ b/.changeset/eighty-forks-fry.md @@ -0,0 +1,5 @@ +--- +'@backstage/techdocs-common': patch +--- + +Use docs/README.md or README.md as fallback if docs/index.md is missing diff --git a/.changeset/few-fishes-heal.md b/.changeset/few-fishes-heal.md new file mode 100644 index 0000000000..9fc9e0d17f --- /dev/null +++ b/.changeset/few-fishes-heal.md @@ -0,0 +1,9 @@ +--- +'@backstage/plugin-techdocs': patch +--- + +Add `` as an alternative to `` that +shows a grid of card instead of table. + +Extend `` to display the entity title of the entity instead of the +name if available. diff --git a/.changeset/four-days-sneeze.md b/.changeset/four-days-sneeze.md new file mode 100644 index 0000000000..93517d3a73 --- /dev/null +++ b/.changeset/four-days-sneeze.md @@ -0,0 +1,6 @@ +--- +'@backstage/plugin-techdocs': patch +'@backstage/plugin-techdocs-backend': patch +--- + +Display entity title (if defined) in titles of TechDocs search results diff --git a/.changeset/hip-pens-love.md b/.changeset/hip-pens-love.md new file mode 100644 index 0000000000..d1549789bf --- /dev/null +++ b/.changeset/hip-pens-love.md @@ -0,0 +1,5 @@ +--- +'@backstage/plugin-catalog-backend': patch +--- + +Take CatalogParser in account when processing file locations. diff --git a/.changeset/hot-wolves-share.md b/.changeset/hot-wolves-share.md new file mode 100644 index 0000000000..a6294b8c9c --- /dev/null +++ b/.changeset/hot-wolves-share.md @@ -0,0 +1,5 @@ +--- +'@backstage/plugin-catalog-backend': patch +--- + +Minor rearrangement of `Stitcher` to clarify the scope of one stitch round diff --git a/.changeset/khaki-pants-vanish.md b/.changeset/khaki-pants-vanish.md new file mode 100644 index 0000000000..df58365e28 --- /dev/null +++ b/.changeset/khaki-pants-vanish.md @@ -0,0 +1,5 @@ +--- +'@backstage/plugin-bazaar': patch +--- + +Bumped plugin-catalog-react version from 0.5.0 to 0.6.0 diff --git a/.changeset/large-dragons-design.md b/.changeset/large-dragons-design.md new file mode 100644 index 0000000000..e1d5a913fe --- /dev/null +++ b/.changeset/large-dragons-design.md @@ -0,0 +1,5 @@ +--- +'@backstage/plugin-sentry': patch +--- + +fix: parameter name on call to sentry api diff --git a/.changeset/lucky-plums-brake.md b/.changeset/lucky-plums-brake.md new file mode 100644 index 0000000000..80eb7b4cb4 --- /dev/null +++ b/.changeset/lucky-plums-brake.md @@ -0,0 +1,5 @@ +--- +'@backstage/plugin-user-settings': patch +--- + +Align grid height diff --git a/.changeset/lucky-pumas-cross.md b/.changeset/lucky-pumas-cross.md new file mode 100644 index 0000000000..4a8e0c5f2f --- /dev/null +++ b/.changeset/lucky-pumas-cross.md @@ -0,0 +1,5 @@ +--- +'@backstage/core-components': patch +--- + +Fixed invalid wrap in DismissableBanner component diff --git a/.changeset/mean-glasses-play.md b/.changeset/mean-glasses-play.md new file mode 100644 index 0000000000..e8a0337843 --- /dev/null +++ b/.changeset/mean-glasses-play.md @@ -0,0 +1,5 @@ +--- +'@backstage/backend-common': patch +--- + +Add "rate limit exceeded" to error from GithubUrlReader if that is the cause of a read failure diff --git a/.changeset/moody-bats-matter.md b/.changeset/moody-bats-matter.md new file mode 100644 index 0000000000..a2c974cd09 --- /dev/null +++ b/.changeset/moody-bats-matter.md @@ -0,0 +1,5 @@ +--- +'@backstage/config-loader': minor +--- + +Removed the `EnvFunc` public export. Its only usage was to be passed in to `LoadConfigOptions.experimentalEnvFunc`. If you were using this type, add a definition in your own project instead with the signature `(name: string) => Promise`. diff --git a/.changeset/nice-pillows-move.md b/.changeset/nice-pillows-move.md new file mode 100644 index 0000000000..5649096d10 --- /dev/null +++ b/.changeset/nice-pillows-move.md @@ -0,0 +1,5 @@ +--- +'@backstage/plugin-azure-devops-backend': patch +--- + +Re-exported types from azure-devops-node-api in @backstage/plugin-azure-devops-backend. diff --git a/.changeset/polite-eyes-punch.md b/.changeset/polite-eyes-punch.md new file mode 100644 index 0000000000..fed1116bb2 --- /dev/null +++ b/.changeset/polite-eyes-punch.md @@ -0,0 +1,5 @@ +--- +'@backstage/plugin-kubernetes-backend': patch +--- + +add caData support for kubernetes client config diff --git a/.changeset/quick-frogs-double.md b/.changeset/quick-frogs-double.md new file mode 100644 index 0000000000..c083abe609 --- /dev/null +++ b/.changeset/quick-frogs-double.md @@ -0,0 +1,6 @@ +--- +'@backstage/config-loader': patch +'@backstage/errors': patch +--- + +Add public tags and documentation diff --git a/.changeset/real-mice-beg.md b/.changeset/real-mice-beg.md new file mode 100644 index 0000000000..7dde97f6c2 --- /dev/null +++ b/.changeset/real-mice-beg.md @@ -0,0 +1,7 @@ +--- +'@backstage/errors': patch +--- + +Two new helpers have been added that make it easier to migrate to considering thrown errors to be of the type `unknown` in TypeScript. The helpers are `assertError` and `isError`, and can be called to make sure that an unknown value conforms to the shape of an `ErrorLike` object. The `assertError` function is a type-guard that throws in the case of a mismatch, while `isError` returns false. + +A new error constructor has also been added, `ForwardedError`, which can be used to add context to a forwarded error. It requires both a message and a cause, and inherits the `name` property from the `cause`. diff --git a/.changeset/sharp-crabs-stare.md b/.changeset/sharp-crabs-stare.md new file mode 100644 index 0000000000..a81e83686f --- /dev/null +++ b/.changeset/sharp-crabs-stare.md @@ -0,0 +1,5 @@ +--- +'@backstage/plugin-catalog-backend': patch +--- + +Add a `GitHubOrgEntityProvider` that can be used instead of the `GithubOrgReaderProcessor`. diff --git a/.changeset/swift-pugs-serve.md b/.changeset/swift-pugs-serve.md new file mode 100644 index 0000000000..8262a66d7f --- /dev/null +++ b/.changeset/swift-pugs-serve.md @@ -0,0 +1,12 @@ +--- +'@backstage/core-app-api': patch +'@backstage/core-plugin-api': patch +'@backstage/plugin-auth-backend': patch +'@backstage/plugin-user-settings': patch +--- + +Atlassian auth provider + +- AtlassianAuth added to core-app-api +- Atlassian provider added to plugin-auth-backend +- Updated user-settings with Atlassian connection diff --git a/.changeset/tiny-panthers-jump.md b/.changeset/tiny-panthers-jump.md new file mode 100644 index 0000000000..d059b826da --- /dev/null +++ b/.changeset/tiny-panthers-jump.md @@ -0,0 +1,22 @@ +--- +'@backstage/backend-common': patch +'@backstage/cli': patch +'@backstage/config-loader': patch +'@backstage/core-app-api': patch +'@backstage/core-components': patch +'@backstage/core-plugin-api': patch +'@backstage/create-app': patch +'@backstage/techdocs-common': patch +'@backstage/plugin-auth-backend': patch +'@backstage/plugin-catalog': patch +'@backstage/plugin-catalog-backend': patch +'@backstage/plugin-catalog-backend-module-ldap': patch +'@backstage/plugin-catalog-import': patch +'@backstage/plugin-catalog-react': patch +'@backstage/plugin-code-coverage-backend': patch +'@backstage/plugin-kubernetes-backend': patch +'@backstage/plugin-scaffolder-backend': patch +'@backstage/plugin-techdocs-backend': patch +--- + +Internal updates to apply more strict checks to throw errors. diff --git a/.changeset/twelve-candles-mix.md b/.changeset/twelve-candles-mix.md new file mode 100644 index 0000000000..3218b2997c --- /dev/null +++ b/.changeset/twelve-candles-mix.md @@ -0,0 +1,5 @@ +--- +'@backstage/plugin-catalog-backend': patch +--- + +Use entity title (if defined) as title of documents indexed by `DefaultCatalogCollator` diff --git a/.changeset/two-ties-eat.md b/.changeset/two-ties-eat.md new file mode 100644 index 0000000000..69edfb16c8 --- /dev/null +++ b/.changeset/two-ties-eat.md @@ -0,0 +1,5 @@ +--- +'@backstage/catalog-model': patch +--- + +Improved documentation for exported symbols. diff --git a/.changeset/wise-hats-remember.md b/.changeset/wise-hats-remember.md new file mode 100644 index 0000000000..6666502bee --- /dev/null +++ b/.changeset/wise-hats-remember.md @@ -0,0 +1,5 @@ +--- +'@backstage/plugin-catalog-backend-module-msgraph': patch +--- + +Add `MicrosoftGraphOrgEntityProvider` as an alternative to `MicrosoftGraphOrgReaderProcessor` that automatically handles user and group deletions. diff --git a/.github/styles/vocab.txt b/.github/styles/vocab.txt index a38baab3dc..eea86a6097 100644 --- a/.github/styles/vocab.txt +++ b/.github/styles/vocab.txt @@ -8,6 +8,7 @@ apis args asciidoc async +Atlassian automations autoscaling Autoscaling diff --git a/ADOPTERS.md b/ADOPTERS.md index f96cc08e18..2d2583be95 100644 --- a/ADOPTERS.md +++ b/ADOPTERS.md @@ -1,60 +1,61 @@ -| Organization | Contact | Description of Use | -| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [Spotify](https://www.spotify.com) | [@leemills83](https://github.com/leemills83) | Main interface towards all of Spotify's infrastructure and technical documentation. | -| [bol.com](https://www.bol.com) | [@sagacity](https://github.com/sagacity) | Initial work being done to unify platform tooling. | -| [DFDS](https://www.dfds.com) | [@carlsendk](https://github.com/carlsendk) | V2 self-service platform. | -| [Roadie](https://roadie.io) | [@dtuite](https://github.com/dtuite) | Hosted, managed Backstage with easy set-up | -| [Roku](https://www.roku.com) | [@timurista](https://github.com/timurista) | Initial work on Cloud engineering service platform. | -| [SDA SE](https://sda.se) | [@Fox32](https://github.com/Fox32) | Central place for developing and sharing services in our insurance ecosystem. | -| [H-E-B](https://www.heb.com) | [@german-j-rodriguez](https://github.com/german-j-rodriguez) | Initial work on Engineering Portal service platform. | -| [American Airlines](https://www.aa.com) | [@paulpach](https://github.com/paulpach) | Central place for developers to develop and maintain applications | -| [Kiwi.com](https://kiwi.com) | [@aexvir](https://github.com/aexvir) | Replacing the frontend of [The Zoo](https://github.com/kiwicom/the-zoo), their service registry. | -| [Voi](https://www.voiscooters.com/) | [@K-Phoen](https://github.com/K-Phoen) | Developer portal, main gateway to our infrastructure, documentation and internal tooling. | -| [Talkdesk](https://www.talkdesk.com) | [@jaime-talkdesk](https://github.com/jaime-talkdesk) | Initial work for Engineering Portal and Self Provisioning to R&D | -| [Wealthsimple](https://www.wealthsimple.com) | [@andrewthauer](https://github.com/andrewthauer) | Developer portal, service catalog, documentation and tooling | -| [Grab](https://www.grab.com) | [@althafh](https://github.com/althafh) | Initial work as a unified interface for all of Grab's internal tooling | -| [Telenor Sweden](https://www.telenor.se) | [@O5ten](https://github.com/O5ten) | Building a developer portal for scaffolding projects towards our unified build environment and microservice stacks | -| [Fiverr](https://www.fiverr.com) | [@nirga](https://github.com/nirga) | Unifying separate tools that developers are using today (i.e. monitoring, dead letter queues management, etc.) into a single platform. | -| [Zalando SE](https://www.zalando.de) | [@leviferreira](https://github.com/leviferreira) | Building V2 of the Internal Development Portal. | -| [LegalZoom](https://legalzoom.com) | [@backjo](https://github.com/backjo) | Developer portal - hub for all engineering projects and metadata. | -| [Expedia Group](https://www.expediagroup.com) | [Mike Turner](mailto:miturner@expediagroup.com), [Sneha Kumar](mailto:snkumar@expediagroup.com), [@guillermomanzo](https://github.com/guillermomanzo), [Erik Lindgren](https://github.com/lindgren) | EG Common Developer Toolkit | -| [Paddle.com](https://paddle.com) | [Ioannis Georgoulas](https://github.com/geototti21) | Developer portal (Tech Docs, Service Catalog, Internal Tooling), we use vanilla Backstage FE and custom BE implementation in Go | -| [Acast.com](https://acast.com) | [Olle Lundberg](https://github.com/lndbrg) | Developer portal with tech docs, service catalog and a bunch of other internal tooling | -| [Lunar](https://lunar.app) | [Jacob Valdemar](https://github.com/JacobValdemar) | Internal developer portal for service overview and insights, API documentation, technical guides, onboarding guides and RFC's. | -| [Trendyol](https://trendyol.com) | [Gamze Senturk](https://github.com/gmzsenturk), [Mert Can Bilgic](https://github.com/mertcb) | The Developer Portal has been called `Pandora`. Provides an overview of Trendyol tech ecosystem. TechDocs, Catalog, Custom Plugins and Theme. | -| [Peloton](https://www.onepeloton.com/) | [Jim Haughwout](https://github.com/JimHaughwout) | Creating our first developer portal and tech-docs. Exploring Service Catalog, Tech Insights and Cost Insights as well. | -| [TELUS](https://telus.com) | [Seb Barre](https://github.com/sbarre) | The Go-to place to find answers about development and delivery at TELUS. | -| [Brex](https://www.brex.com/) | [Vamsi Chitters](https://github.com/vamsikc) | A centralized UI to understand how a service fits in the whole Brex architecture and manage a team’s engineering dependencies. | -| [Oriflame](https://www.oriflame.com/) | [Oriflame](https://github.com/oriflame) | Internal developer portal for services, single page apps and packages overview, API documentation, technical guides, tech-radar and more. | -| [Booz Allen Hamilton](https://www.boozallen.com/) | [Jason Miller](https://github.com/JasonMiller-BAH) | Developer portal for a full-stack software development ecosystem that accelerates consistent and repeatable Modern Software Development practices for internal innovation and investments. | -| [Netflix](https://www.netflix.com/) | [bleathem](https://github.com/bleathem) | Our Backstage implementation will be the front door to a unified experience connecting our internal platform products across important workflows with integrated knowledge and support. | -| [b.well](https://www.icanbwell.com/) | [Jacob Rosales](https://github.com/jrosales) | Foundation for our engineering portal and cloud insights. | -| [PagerDuty](https://www.pagerduty.com/) | [Mark Shaw](https://github.com/markshawtoronto) | Developer portal, initially focused on software templates and tech-docs. | -| [MoonShiner](https://moonshiner.at) | [Fabian Hippmann](https://github.com/FabianHippmann) | Developer portal - helps us keep track of our customer projects, onboard new developers & improve our development process πŸŒ•πŸš€πŸ§‘β€πŸš€ | -| [FundApps](https://www.fundapps.co/) | [Elliot Greenwood](https://github.com/egnwd) | Developer Portal - A place for us to keep track of our projects and documentation for all services and processes | -| [DAZN](https://dazn.com/) | [Lou Bichard](https://twitter.com/loujaybee), [Marco Crivellaro](https://github.com/crivetechie), [Alex Hollerith](mailto:alex.hollerith@dazn.com) | Ingesting all of DAZN's repos for the catalog, migrating our internal platform apps (pull request boards, release information, inner source marketplace etc) to Backstage plugins (where applicable). | -| [HelloFresh](https://www.hellofresh.de/) | [@iammuho](https://github.com/iammuho), [@ElenaForester](https://github.com/ElenaForester), [@diegomarangoni](https://github.com/diegomarangoni) | Our developer portal at HelloFresh - Spread across an organisation of 500+ engineers globally. | -| [FactSet](https://www.factset.com/) | [@kuangp](https://github.com/kuangp) | Developer portal to provide discoverability to all internal components, APIs, documentation, and scaffold templates with integrations to our internal infrastructure tools. | -| [Workrise](https://www.workrise.com/) | [Michael Rode](https://github.com/michaelrode) | Developer portal, main gateway to our infrastructure, documentation and internal tooling. | -| [RedVentures](https://www.redventures.com/) | [Chris Diaz](https://github.com/codingdiaz) | Developer portal that brings everything an engineer needs to provide value into a single pane of glass. | -| [MavTek](https://www.mavtek.com/) | [@fgascon](https://github.com/fgascon) | Developer portal focused on standardizing practices, centralizing documentation and streamlining developer practices. | -| [QuintoAndar](https://www.quintoandar.com.br/) | [@quintoandar](https://github.com/quintoandar) | Developer portal, services catalog and centralization of service metrics. | -| [empathy.co](https://empathy.co/) | [@guillermotti](https://github.com/guillermotti) | Developer portal for tech docs, service catalog, plugin discovery and much more. | -| [creditas.com](https://creditas.com/) | [@aureliosaraiva](https://github.com/aureliosaraiva) [@Creditas](https://github.com/creditas) | Centralization of all services, standards, documentation, etc. We started the deployment process. | -| [Prisjakt](https://www.prisjakt.nu) / [PriceSpy](https://pricespy.co.uk) | [@kennylindahl](https://github.com/kennylindahl) | Internal developer portal - Documentation, scaffolding, software catalog, TechRadar, Gitlab org data integration | -| [Powerspike](https://powerspike.tv/) | [@trelore](https://github.com/trelore) | Developer portal for documentation of core libraries and repositories. | -| [2U](https://2u.com) | [Andrew Thal](https://github.com/athal7) | Development team home-base, promoting service discoverability, resource dependencies, and tech radar | -| [Taxfix](https://taxfix.de/) | [Sami Ur Rehman](https://github.com/samiurrehman92) | Developer's portal with software catalog at it's core. Hosts API Specs, Tech Docs, Tech Radar and some custom plugins. | -| [Busuu](https://busuu.com/) | [Adam Tester](https://github.com/adamtester) | Developer portal with service catalog, API docs, Event docs, service templating, and cost insights. | -| [Loadsmart](https://loadsmart.com/) | [Loadsmart](https://github.com/loadsmart) | Improve services visibility and operations for service owners and developers. | -| [Monzo](https://monzo.com/) | [@WillSewell](https://github.com/WillSewell), [@joechrisellis](https://github.com/joechrisellis) | Developer portal showing metadata and docs for over 2000 microservices. We have built a number of plugins such as a UI for our system to measure [software excellence](https://monzo.com/blog/2021/09/15/how-we-measure-software-excellence), and a UI to show deployment and config change events. | -| [Vaimo](https://www.vaimo.com) | [@vaimo-magnus](https://github.com/vaimo-magnus) | Developer Portal for our developers at Vaimo, currently docs and self-service towards our internal PaaS based on k8s. Plans to extend the catalog into Projects, Environments etc | -| [Wayfair](https://www.wayfair.com) | [@fransan](https://github.com/fransan), [@errskipower](https://github.com/errskipower), [@hrrs](https://github.com/hrrs) | Developer portal for service catalog, technical documentation, and APIs. | -| [CircleHD](https://www.circlehd.com) | [@circlehddev](https://github.com/circlehddev) | Developer Portal for internal dev team across the globe | -| [CastDesk](https://castdesk.com) | [@circlehddev](https://github.com/circlehddev) | Developer Portal for internal dev team across the globe | -| [Santagostino](https://santagostino.it) | [@santagostino](https://github.com/santagostino) | Developer portal, gateway to our infrastructure, documentation, service catalog and internal tooling. | -| [Peak](https://peak.ai) | [Luke Beamish](https://github.com/lukebeamish-peak) | Developer portal for all internal engineers to access documentation and tooling. | -| [Gelato](https://gelato.com/) | [Dmitry Makarenko](https://github.com/dmitry-makarenko-gelato) | Developer portal: documentation, service templates, org structure, service catalog, plugins for integration with internal and third-party systemsπŸš€. | -| [GoCardless](https://gocardless.com/) | [James Turley](https://github.com/tragiclifestories) | Developer portal: documentation, service templates, org structure, service catalog, plugins for integration with internal systems. | -| [Box](https://www.box.com) | [@kielosz](https://github.com/kielosz), [@jluk-box](https://github.com/jluk-box), [@ptychu](https://github.com/ptychu), [@alexrybch](https://github.com/alexrybch), [@szubster](https://github.com/szubster) | Developer portal for service catalog, integration with internal systems, new service onboarding. | -| [Bazaarvoice](https://www.bazaarvoice.com) | [@niallmccullagh](https://github.com/niallmccullagh) | Developer portal for service catalog and scaffolds, publishing Github docs and API documentation, visualising our internal tech radar and our product engineering org structure. | +| Organization | Contact | Description of Use | +| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Spotify](https://www.spotify.com) | [@leemills83](https://github.com/leemills83) | Main interface towards all of Spotify's infrastructure and technical documentation. | +| [bol.com](https://www.bol.com) | [@sagacity](https://github.com/sagacity) | Initial work being done to unify platform tooling. | +| [DFDS](https://www.dfds.com) | [@carlsendk](https://github.com/carlsendk) | V2 self-service platform. | +| [Roadie](https://roadie.io) | [@dtuite](https://github.com/dtuite) | Hosted, managed Backstage with easy set-up | +| [Roku](https://www.roku.com) | [@timurista](https://github.com/timurista) | Initial work on Cloud engineering service platform. | +| [SDA SE](https://sda.se) | [@Fox32](https://github.com/Fox32) | Central place for developing and sharing services in our insurance ecosystem. | +| [H-E-B](https://www.heb.com) | [@german-j-rodriguez](https://github.com/german-j-rodriguez) | Initial work on Engineering Portal service platform. | +| [American Airlines](https://www.aa.com) | [@paulpach](https://github.com/paulpach) | Central place for developers to develop and maintain applications | +| [Kiwi.com](https://kiwi.com) | [@aexvir](https://github.com/aexvir) | Replacing the frontend of [The Zoo](https://github.com/kiwicom/the-zoo), their service registry. | +| [Voi](https://www.voiscooters.com/) | [@K-Phoen](https://github.com/K-Phoen) | Developer portal, main gateway to our infrastructure, documentation and internal tooling. | +| [Talkdesk](https://www.talkdesk.com) | [@jaime-talkdesk](https://github.com/jaime-talkdesk) | Initial work for Engineering Portal and Self Provisioning to R&D | +| [Wealthsimple](https://www.wealthsimple.com) | [@andrewthauer](https://github.com/andrewthauer) | Developer portal, service catalog, documentation and tooling | +| [Grab](https://www.grab.com) | [@althafh](https://github.com/althafh) | Initial work as a unified interface for all of Grab's internal tooling | +| [Telenor Sweden](https://www.telenor.se) | [@O5ten](https://github.com/O5ten) | Building a developer portal for scaffolding projects towards our unified build environment and microservice stacks | +| [Fiverr](https://www.fiverr.com) | [@nirga](https://github.com/nirga) | Unifying separate tools that developers are using today (i.e. monitoring, dead letter queues management, etc.) into a single platform. | +| [Zalando SE](https://www.zalando.de) | [@leviferreira](https://github.com/leviferreira) | Building V2 of the Internal Development Portal. | +| [LegalZoom](https://legalzoom.com) | [@backjo](https://github.com/backjo) | Developer portal - hub for all engineering projects and metadata. | +| [Expedia Group](https://www.expediagroup.com) | [Mike Turner](mailto:miturner@expediagroup.com), [Sneha Kumar](mailto:snkumar@expediagroup.com), [@guillermomanzo](https://github.com/guillermomanzo), [Erik Lindgren](https://github.com/lindgren) | EG Common Developer Toolkit | +| [Paddle.com](https://paddle.com) | [Ioannis Georgoulas](https://github.com/geototti21) | Developer portal (Tech Docs, Service Catalog, Internal Tooling), we use vanilla Backstage FE and custom BE implementation in Go | +| [Acast.com](https://acast.com) | [Olle Lundberg](https://github.com/lndbrg) | Developer portal with tech docs, service catalog and a bunch of other internal tooling | +| [Lunar](https://lunar.app) | [Jacob Valdemar](https://github.com/JacobValdemar) | Internal developer portal for service overview and insights, API documentation, technical guides, onboarding guides and RFC's. | +| [Trendyol](https://trendyol.com) | [Gamze Senturk](https://github.com/gmzsenturk), [Mert Can Bilgic](https://github.com/mertcb) | The Developer Portal has been called `Pandora`. Provides an overview of Trendyol tech ecosystem. TechDocs, Catalog, Custom Plugins and Theme. | +| [Peloton](https://www.onepeloton.com/) | [Jim Haughwout](https://github.com/JimHaughwout) | Creating our first developer portal and tech-docs. Exploring Service Catalog, Tech Insights and Cost Insights as well. | +| [TELUS](https://telus.com) | [Seb Barre](https://github.com/sbarre) | The Go-to place to find answers about development and delivery at TELUS. | +| [Brex](https://www.brex.com/) | [Vamsi Chitters](https://github.com/vamsikc) | A centralized UI to understand how a service fits in the whole Brex architecture and manage a team’s engineering dependencies. | +| [Oriflame](https://www.oriflame.com/) | [Oriflame](https://github.com/oriflame) | Internal developer portal for services, single page apps and packages overview, API documentation, technical guides, tech-radar and more. | +| [Booz Allen Hamilton](https://www.boozallen.com/) | [Jason Miller](https://github.com/JasonMiller-BAH) | Developer portal for a full-stack software development ecosystem that accelerates consistent and repeatable Modern Software Development practices for internal innovation and investments. | +| [Netflix](https://www.netflix.com/) | [bleathem](https://github.com/bleathem) | Our Backstage implementation will be the front door to a unified experience connecting our internal platform products across important workflows with integrated knowledge and support. | +| [b.well](https://www.icanbwell.com/) | [Jacob Rosales](https://github.com/jrosales) | Foundation for our engineering portal and cloud insights. | +| [PagerDuty](https://www.pagerduty.com/) | [Mark Shaw](https://github.com/markshawtoronto) | Developer portal, initially focused on software templates and tech-docs. | +| [MoonShiner](https://moonshiner.at) | [Fabian Hippmann](https://github.com/FabianHippmann) | Developer portal - helps us keep track of our customer projects, onboard new developers & improve our development process πŸŒ•πŸš€πŸ§‘β€πŸš€ | +| [FundApps](https://www.fundapps.co/) | [Elliot Greenwood](https://github.com/egnwd) | Developer Portal - A place for us to keep track of our projects and documentation for all services and processes | +| [DAZN](https://dazn.com/) | [Lou Bichard](https://twitter.com/loujaybee), [Marco Crivellaro](https://github.com/crivetechie), [Alex Hollerith](mailto:alex.hollerith@dazn.com) | Ingesting all of DAZN's repos for the catalog, migrating our internal platform apps (pull request boards, release information, inner source marketplace etc) to Backstage plugins (where applicable). | +| [HelloFresh](https://www.hellofresh.de/) | [@iammuho](https://github.com/iammuho), [@ElenaForester](https://github.com/ElenaForester), [@diegomarangoni](https://github.com/diegomarangoni) | Our developer portal at HelloFresh - Spread across an organisation of 500+ engineers globally. | +| [FactSet](https://www.factset.com/) | [@kuangp](https://github.com/kuangp) | Developer portal to provide discoverability to all internal components, APIs, documentation, and scaffold templates with integrations to our internal infrastructure tools. | +| [Workrise](https://www.workrise.com/) | [Michael Rode](https://github.com/michaelrode) | Developer portal, main gateway to our infrastructure, documentation and internal tooling. | +| [RedVentures](https://www.redventures.com/) | [Chris Diaz](https://github.com/codingdiaz) | Developer portal that brings everything an engineer needs to provide value into a single pane of glass. | +| [MavTek](https://www.mavtek.com/) | [@fgascon](https://github.com/fgascon) | Developer portal focused on standardizing practices, centralizing documentation and streamlining developer practices. | +| [QuintoAndar](https://www.quintoandar.com.br/) | [@quintoandar](https://github.com/quintoandar) | Developer portal, services catalog and centralization of service metrics. | +| [empathy.co](https://empathy.co/) | [@guillermotti](https://github.com/guillermotti) | Developer portal for tech docs, service catalog, plugin discovery and much more. | +| [creditas.com](https://creditas.com/) | [@aureliosaraiva](https://github.com/aureliosaraiva) [@Creditas](https://github.com/creditas) | Centralization of all services, standards, documentation, etc. We started the deployment process. | +| [Prisjakt](https://www.prisjakt.nu) / [PriceSpy](https://pricespy.co.uk) | [@kennylindahl](https://github.com/kennylindahl) | Internal developer portal - Documentation, scaffolding, software catalog, TechRadar, Gitlab org data integration | +| [Powerspike](https://powerspike.tv/) | [@trelore](https://github.com/trelore) | Developer portal for documentation of core libraries and repositories. | +| [2U](https://2u.com) | [Andrew Thal](https://github.com/athal7) | Development team home-base, promoting service discoverability, resource dependencies, and tech radar | +| [Taxfix](https://taxfix.de/) | [Sami Ur Rehman](https://github.com/samiurrehman92) | Developer's portal with software catalog at it's core. Hosts API Specs, Tech Docs, Tech Radar and some custom plugins. | +| [Busuu](https://busuu.com/) | [Adam Tester](https://github.com/adamtester) | Developer portal with service catalog, API docs, Event docs, service templating, and cost insights. | +| [Loadsmart](https://loadsmart.com/) | [Loadsmart](https://github.com/loadsmart) | Improve services visibility and operations for service owners and developers. | +| [Monzo](https://monzo.com/) | [@WillSewell](https://github.com/WillSewell), [@joechrisellis](https://github.com/joechrisellis) | Developer portal showing metadata and docs for over 2000 microservices. We have built a number of plugins such as a UI for our system to measure [software excellence](https://monzo.com/blog/2021/09/15/how-we-measure-software-excellence), and a UI to show deployment and config change events. | +| [Vaimo](https://www.vaimo.com) | [@vaimo-magnus](https://github.com/vaimo-magnus) | Developer Portal for our developers at Vaimo, currently docs and self-service towards our internal PaaS based on k8s. Plans to extend the catalog into Projects, Environments etc | +| [Wayfair](https://www.wayfair.com) | [@fransan](https://github.com/fransan), [@errskipower](https://github.com/errskipower), [@hrrs](https://github.com/hrrs) | Developer portal for service catalog, technical documentation, and APIs. | +| [CircleHD](https://www.circlehd.com) | [@circlehddev](https://github.com/circlehddev) | Developer Portal for internal dev team across the globe | +| [CastDesk](https://castdesk.com) | [@circlehddev](https://github.com/circlehddev) | Developer Portal for internal dev team across the globe | +| [Santagostino](https://santagostino.it) | [@santagostino](https://github.com/santagostino) | Developer portal, gateway to our infrastructure, documentation, service catalog and internal tooling. | +| [Peak](https://peak.ai) | [Luke Beamish](https://github.com/lukebeamish-peak) | Developer portal for all internal engineers to access documentation and tooling. | +| [Gelato](https://gelato.com/) | [Dmitry Makarenko](https://github.com/dmitry-makarenko-gelato) | Developer portal: documentation, service templates, org structure, service catalog, plugins for integration with internal and third-party systemsπŸš€. | +| [GoCardless](https://gocardless.com/) | [James Turley](https://github.com/tragiclifestories) | Developer portal: documentation, service templates, org structure, service catalog, plugins for integration with internal systems. | +| [Box](https://www.box.com) | [@kielosz](https://github.com/kielosz), [@jluk-box](https://github.com/jluk-box), [@ptychu](https://github.com/ptychu), [@alexrybch](https://github.com/alexrybch), [@szubster](https://github.com/szubster) | Developer portal for service catalog, integration with internal systems, new service onboarding. | +| [Bazaarvoice](https://www.bazaarvoice.com) | [@niallmccullagh](https://github.com/niallmccullagh) | Developer portal for service catalog and scaffolds, publishing Github docs and API documentation, visualising our internal tech radar and our product engineering org structure. | +| [Krateo PlatformOps](https://www.krateo.io) | [@projectkerberus](https://github.com/projectkerberus) | A multi-cloud control plane to create, manage and deploy any kind of resource easily and centrally via a Developer Portal that centralizes via a self-service catalog the templating and ownership of services, the available documentation, the overview of the components that compose an entire domain and all the data of the service lifecycle. | diff --git a/app-config.yaml b/app-config.yaml index c24ac1701b..e1b648c472 100644 --- a/app-config.yaml +++ b/app-config.yaml @@ -364,6 +364,11 @@ auth: development: clientId: ${AUTH_BITBUCKET_CLIENT_ID} clientSecret: ${AUTH_BITBUCKET_CLIENT_SECRET} + atlassian: + development: + clientId: ${AUTH_ATLASSIAN_CLIENT_ID} + clientSecret: ${AUTH_ATLASSIAN_CLIENT_SECRET} + scopes: ${AUTH_ATLASSIAN_SCOPES} costInsights: engineerCost: 200000 products: diff --git a/docs/auth/atlassian/provider.md b/docs/auth/atlassian/provider.md new file mode 100644 index 0000000000..38774ca3cc --- /dev/null +++ b/docs/auth/atlassian/provider.md @@ -0,0 +1,64 @@ +--- +id: provider +title: Atlassian Authentication Provider +sidebar_label: Atlassian +description: Adding Atlassian as an authentication provider in Backstage +--- + +The Backstage `core-plugin-api` package comes with an Atlassian authentication +provider that can authenticate users using Atlassian products. This auth +**only** provides scopes for the following APIs: + +- Confluence API +- User REST API +- Jira platform REST API +- Jira Service Desk API +- Personal data reporting API +- User identity API + +## Create an OAuth 2.0 (3LO) app in the Atlassian developer console + +To add Atlassian authentication, you must create an OAuth 2.0 (3LO) app. + +Go to `https://developer.atlassian.com/console/myapps/`. + +Click on the drop down `Create`, and choose `OAuth 2.0 integration`. + +Name your integration and click on the `Create` button. + +Settings for local development: + +- Callback URL: `http://localhost:7000/api/auth/atlassian` +- Use rotating refresh tokens +- For permissions, you **must** enable `View user profile` for the currently + logged-in user, under `User identity API` + +## Configuration + +The provider configuration can then be added to your `app-config.yaml` under the +root `auth` configuration: + +```yaml +auth: + environment: development + providers: + atlassian: + development: + clientId: ${AUTH_ATLASSIAN_CLIENT_ID} + clientSecret: ${AUTH_ATLASSIAN_CLIENT_SECRET} + scopes: ${AUTH_ATLASSIAN_SCOPES} +``` + +The Atlassian provider is a structure with three configuration keys: + +- `clientId`: The Key you generated in the developer console. +- `clientSecret`: The Secret tied to the generated Key. +- `scopes`: List of scopes the app has permissions for, separated by spaces. + +**NOTE:** the scopes `offline_access` and `read:me` are provided by default. + +## Adding the provider to the Backstage frontend + +To add the provider to the frontend, add the `atlassianAuthApi` reference and +`SignInPage` component as shown in +[Adding the provider to the sign-in page](../index.md#adding-the-provider-to-the-sign-in-page). diff --git a/docs/features/kubernetes/configuration.md b/docs/features/kubernetes/configuration.md index f48faa202d..6b3991144b 100644 --- a/docs/features/kubernetes/configuration.md +++ b/docs/features/kubernetes/configuration.md @@ -29,6 +29,7 @@ kubernetes: serviceAccountToken: ${K8S_MINIKUBE_TOKEN} dashboardUrl: http://127.0.0.1:64713 # url copied from running the command: minikube service kubernetes-dashboard -n kubernetes-dashboard dashboardApp: standard + caData: ${K8S_CONFIG_CA_DATA} - url: http://127.0.0.2:9999 name: aws-cluster-1 authProvider: 'aws' @@ -135,6 +136,24 @@ See also https://github.com/backstage/backstage/tree/master/plugins/kubernetes/src/utils/clusterLinks/formatters for real examples. +##### `clusters.\*.caData` (optional) + +PEM-encoded certificate authority certificates. + +This values could be obtained via inspecting the Kubernetes config file (usually +at `~/.kube/config`) under `clusters.cluster.certificate-authority-data`. For +GKE, execute the following command to obtain the value + +``` +gcloud container clusters describe \ + --zone= \ + --format="value(masterAuth.clusterCaCertificate)" +``` + +See also +https://cloud.google.com/kubernetes-engine/docs/how-to/api-server-authentication#environments-without-gcloud +for complete docs about GKE without `gcloud`. + #### `gke` This cluster locator is designed to work with Kubernetes clusters running in diff --git a/docs/features/techdocs/creating-and-publishing.md b/docs/features/techdocs/creating-and-publishing.md index c0989bf02e..ec27a81653 100644 --- a/docs/features/techdocs/creating-and-publishing.md +++ b/docs/features/techdocs/creating-and-publishing.md @@ -38,7 +38,7 @@ up and running and to start writing your documentation. If you have created software templates that do not include documentation by default, we highly recommend you to set that up. Follow our how-to guide -[How to add documentation setup to your software templates](./how-to-guides.md#how-to-add-documentation-setup-to-your-software-templates) +[How to add documentation setup to your software templates](./how-to-guides.md#how-to-add-the-documentation-setup-to-your-software-templates) to get started. ### Use the documentation template diff --git a/docs/features/techdocs/getting-started.md b/docs/features/techdocs/getting-started.md index 0b1809dc22..d79f6bb891 100644 --- a/docs/features/techdocs/getting-started.md +++ b/docs/features/techdocs/getting-started.md @@ -215,10 +215,10 @@ techdocs: publisher: type: 'local' generator: - techdocs: local + runIn: local ``` -Setting `generators.techdocs` to `local` means you will have to make sure your +Setting `generator.runIn` to `local` means you will have to make sure your environment is compatible with techdocs. You will have to install the `mkdocs` and `mkdocs-techdocs-core` package from diff --git a/docs/features/techdocs/how-to-guides.md b/docs/features/techdocs/how-to-guides.md index edca4e84ad..8ff486af37 100644 --- a/docs/features/techdocs/how-to-guides.md +++ b/docs/features/techdocs/how-to-guides.md @@ -110,7 +110,8 @@ TechDocs uses a composability pattern similar to the Search and Catalog plugins in Backstage. While a default table experience, similar to the one provided by the Catalog plugin, is made available for ease-of-use, it's possible for you to provide a completely custom experience, tailored to the needs of your -organization. +organization. For example, TechDocs comes with an alternative grid based layout +(``). This is done in your `app` package. By default, you might see something like this in your `App.tsx`: diff --git a/docs/integrations/azure/org.md b/docs/integrations/azure/org.md index c359960f4d..8e17bb2cc1 100644 --- a/docs/integrations/azure/org.md +++ b/docs/integrations/azure/org.md @@ -7,7 +7,7 @@ description: Importing users and groups from a Microsoft Azure Active Directory --- The Backstage catalog can be set up to ingest organizational data - users and -teams - directly from an tenant in Microsoft Azure Active Directory via the +teams - directly from a tenant in Microsoft Azure Active Directory via the Microsoft Graph API. More details on this are available in the diff --git a/microsite/sidebars.json b/microsite/sidebars.json index cdbfdccec3..bee9cd7180 100644 --- a/microsite/sidebars.json +++ b/microsite/sidebars.json @@ -213,6 +213,7 @@ "label": "Included providers", "ids": [ "auth/auth0/provider", + "auth/atlassian/provider", "auth/bitbucket/provider", "auth/microsoft/provider", "auth/github/provider", diff --git a/packages/backend-common/src/database/connectors/postgres.ts b/packages/backend-common/src/database/connectors/postgres.ts index f6e42d1945..62de2e001e 100644 --- a/packages/backend-common/src/database/connectors/postgres.ts +++ b/packages/backend-common/src/database/connectors/postgres.ts @@ -17,6 +17,7 @@ import knexFactory, { Knex } from 'knex'; import { Config } from '@backstage/config'; +import { ForwardedError } from '@backstage/errors'; import { mergeDatabaseConfig } from '../config'; import { DatabaseConnector } from '../types'; import defaultNameOverride from './defaultNameOverride'; @@ -94,8 +95,7 @@ function requirePgConnectionString() { try { return require('pg-connection-string').parse; } catch (e) { - const message = `Postgres: Install 'pg-connection-string'`; - throw new Error(`${message}\n${e.message}`); + throw new ForwardedError("Postgres: Install 'pg-connection-string'", e); } } diff --git a/packages/backend-common/src/reading/AwsS3UrlReader.test.ts b/packages/backend-common/src/reading/AwsS3UrlReader.test.ts index 0bc0e4f97f..6959edcc8b 100644 --- a/packages/backend-common/src/reading/AwsS3UrlReader.test.ts +++ b/packages/backend-common/src/reading/AwsS3UrlReader.test.ts @@ -167,7 +167,7 @@ describe('AwsS3UrlReader', () => { ), ).rejects.toThrow( Error( - `Could not retrieve file from S3: not a valid AWS S3 URL: https://test-bucket.s3.us-east-2.NOTamazonaws.com/file.yaml`, + `Could not retrieve file from S3; caused by Error: not a valid AWS S3 URL: https://test-bucket.s3.us-east-2.NOTamazonaws.com/file.yaml`, ), ); }); @@ -216,7 +216,7 @@ describe('AwsS3UrlReader', () => { ), ).rejects.toThrow( Error( - `Could not retrieve file from S3: not a valid AWS S3 URL: https://test-bucket.s3.us-east-2.NOTamazonaws.com/file.yaml`, + `Could not retrieve file from S3; caused by Error: not a valid AWS S3 URL: https://test-bucket.s3.us-east-2.NOTamazonaws.com/file.yaml`, ), ); }); diff --git a/packages/backend-common/src/reading/AwsS3UrlReader.ts b/packages/backend-common/src/reading/AwsS3UrlReader.ts index cb03ec4f71..7fd0f6ba19 100644 --- a/packages/backend-common/src/reading/AwsS3UrlReader.ts +++ b/packages/backend-common/src/reading/AwsS3UrlReader.ts @@ -27,6 +27,7 @@ import { } from './types'; import getRawBody from 'raw-body'; import { AwsS3Integration, ScmIntegrations } from '@backstage/integration'; +import { ForwardedError } from '@backstage/errors'; import { ListObjectsV2Output, ObjectList } from 'aws-sdk/clients/s3'; const parseURL = ( @@ -162,7 +163,7 @@ export class AwsS3UrlReader implements UrlReader { etag: etag, }; } catch (e) { - throw new Error(`Could not retrieve file from S3: ${e.message}`); + throw new ForwardedError('Could not retrieve file from S3', e); } } @@ -203,7 +204,7 @@ export class AwsS3UrlReader implements UrlReader { return await this.deps.treeResponseFactory.fromReadableArray(responses); } catch (e) { - throw new Error(`Could not retrieve file tree from S3: ${e.message}`); + throw new ForwardedError('Could not retrieve file tree from S3', e); } } diff --git a/packages/backend-common/src/reading/GithubUrlReader.test.ts b/packages/backend-common/src/reading/GithubUrlReader.test.ts index e70444cf2c..c76364976d 100644 --- a/packages/backend-common/src/reading/GithubUrlReader.test.ts +++ b/packages/backend-common/src/reading/GithubUrlReader.test.ts @@ -221,6 +221,32 @@ describe('GithubUrlReader', () => { ).rejects.toThrow(NotModifiedError); }); + it('should throw Error with ratelimit exceeded if GitHub responds with 403 and rate limit is exceeded', async () => { + expect.assertions(1); + + worker.use( + rest.get( + 'https://ghe.github.com/api/v3/repos/backstage/mock/tree/contents/', + (_req, res, ctx) => { + return res( + ctx.status(403), + ctx.set('X-RateLimit-Remaining', '0'), + ctx.body( + '{"message": "API rate limit exceeded for xxx.xxx.xxx.xxx..."}', + ), + ); + }, + ), + ); + + await expect( + gheProcessor.readUrl( + 'https://github.com/backstage/mock/tree/blob/main', + { etag: 'foo' }, + ), + ).rejects.toThrow(/rate limit exceeded/); + }); + it('should return etag from the response', async () => { (mockCredentialsProvider.getCredentials as jest.Mock).mockResolvedValue({ headers: { diff --git a/packages/backend-common/src/reading/GithubUrlReader.ts b/packages/backend-common/src/reading/GithubUrlReader.ts index 1eed5764ef..ca16e23fec 100644 --- a/packages/backend-common/src/reading/GithubUrlReader.ts +++ b/packages/backend-common/src/reading/GithubUrlReader.ts @@ -126,10 +126,21 @@ export class GithubUrlReader implements UrlReader { }; } - const message = `${url} could not be read as ${ghUrl}, ${response.status} ${response.statusText}`; + let message = `${url} could not be read as ${ghUrl}, ${response.status} ${response.statusText}`; if (response.status === 404) { throw new NotFoundError(message); } + + // GitHub returns a 403 response with a couple of headers indicating rate + // limit status. See more in the GitHub docs: + // https://docs.github.com/en/rest/overview/resources-in-the-rest-api#rate-limiting + if ( + response.status === 403 && + response.headers.get('X-RateLimit-Remaining') === '0' + ) { + message += ' (rate limit exceeded)'; + } + throw new Error(message); } diff --git a/packages/backend-common/src/reading/integration.test.ts b/packages/backend-common/src/reading/integration.test.ts index ae557be583..951df29605 100644 --- a/packages/backend-common/src/reading/integration.test.ts +++ b/packages/backend-common/src/reading/integration.test.ts @@ -15,6 +15,7 @@ */ import { ConfigReader } from '@backstage/config'; +import { isError } from '@backstage/errors'; import { getVoidLogger } from '../logging'; import { UrlReaders } from './UrlReaders'; @@ -71,7 +72,10 @@ function withRetries(count: number, fn: () => Promise) { error = err; } } - if (!error.message.match(/rate limit|Too Many Requests/)) { + if ( + isError(error) && + !error.message.match(/rate limit|Too Many Requests/) + ) { throw error; } else { console.warn('Request was rate limited', error); diff --git a/packages/backend-common/src/util/DockerContainerRunner.ts b/packages/backend-common/src/util/DockerContainerRunner.ts index da3ce66ec2..b81bd995ca 100644 --- a/packages/backend-common/src/util/DockerContainerRunner.ts +++ b/packages/backend-common/src/util/DockerContainerRunner.ts @@ -16,6 +16,7 @@ import Docker from 'dockerode'; import fs from 'fs-extra'; +import { ForwardedError } from '@backstage/errors'; import { PassThrough } from 'stream'; import { ContainerRunner, RunContainerOptions } from './ContainerRunner'; @@ -45,8 +46,9 @@ export class DockerContainerRunner implements ContainerRunner { try { await this.dockerClient.ping(); } catch (e) { - throw new Error( - `This operation requires Docker. Docker does not appear to be available. Docker.ping() failed with: ${e.message}`, + throw new ForwardedError( + 'This operation requires Docker. Docker does not appear to be available. Docker.ping() failed with', + e, ); } diff --git a/packages/catalog-model/api-report.md b/packages/catalog-model/api-report.md index 1e7eb8fd52..c9429f9bdb 100644 --- a/packages/catalog-model/api-report.md +++ b/packages/catalog-model/api-report.md @@ -9,12 +9,12 @@ import { JsonValue } from '@backstage/config'; import { SerializedError } from '@backstage/errors'; import * as yup from 'yup'; -// @public @deprecated (undocumented) +// @public @deprecated export const analyzeLocationSchema: yup.SchemaOf<{ location: LocationSpec; }>; -// @public (undocumented) +// @public interface ApiEntityV1alpha1 extends Entity { // (undocumented) apiVersion: 'backstage.io/v1alpha1' | 'backstage.io/v1beta1'; @@ -32,7 +32,7 @@ interface ApiEntityV1alpha1 extends Entity { export { ApiEntityV1alpha1 as ApiEntity }; export { ApiEntityV1alpha1 }; -// @public (undocumented) +// @public export const apiEntityV1alpha1Validator: KindValidator; // @public @@ -58,7 +58,7 @@ export function compareEntityToRef( context?: EntityRefContext, ): boolean; -// @public (undocumented) +// @public interface ComponentEntityV1alpha1 extends Entity { // (undocumented) apiVersion: 'backstage.io/v1alpha1' | 'backstage.io/v1beta1'; @@ -79,7 +79,7 @@ interface ComponentEntityV1alpha1 extends Entity { export { ComponentEntityV1alpha1 as ComponentEntity }; export { ComponentEntityV1alpha1 }; -// @public (undocumented) +// @public export const componentEntityV1alpha1Validator: KindValidator; // @public @@ -89,7 +89,7 @@ export class DefaultNamespaceEntityPolicy implements EntityPolicy { enforce(entity: Entity): Promise; } -// @public (undocumented) +// @public interface DomainEntityV1alpha1 extends Entity { // (undocumented) apiVersion: 'backstage.io/v1alpha1' | 'backstage.io/v1beta1'; @@ -103,10 +103,10 @@ interface DomainEntityV1alpha1 extends Entity { export { DomainEntityV1alpha1 as DomainEntity }; export { DomainEntityV1alpha1 }; -// @public (undocumented) +// @public export const domainEntityV1alpha1Validator: KindValidator; -// @public (undocumented) +// @public export const EDIT_URL_ANNOTATION = 'backstage.io/edit-url'; // @public @@ -181,7 +181,7 @@ export type EntityName = { name: string; }; -// @public (undocumented) +// @public export const EntityPolicies: { allOf(policies: EntityPolicy[]): EntityPolicy; oneOf(policies: EntityPolicy[]): EntityPolicy; @@ -250,7 +250,7 @@ export function getEntitySourceLocation(entity: Entity): { target: string; }; -// @public (undocumented) +// @public interface GroupEntityV1alpha1 extends Entity { // (undocumented) apiVersion: 'backstage.io/v1alpha1' | 'backstage.io/v1beta1'; @@ -272,10 +272,10 @@ interface GroupEntityV1alpha1 extends Entity { export { GroupEntityV1alpha1 as GroupEntity }; export { GroupEntityV1alpha1 }; -// @public (undocumented) +// @public export const groupEntityV1alpha1Validator: KindValidator; -// @public (undocumented) +// @public export type JSONSchema = JSONSchema7 & { [key in string]?: JsonValue; }; @@ -305,16 +305,16 @@ export class KubernetesValidatorFunctions { static isValidObjectName(value: unknown): boolean; } -// @public (undocumented) +// @public type Location_2 = { id: string; } & LocationSpec; export { Location_2 as Location }; -// @public (undocumented) +// @public export const LOCATION_ANNOTATION = 'backstage.io/managed-by-location'; -// @public (undocumented) +// @public interface LocationEntityV1alpha1 extends Entity { // (undocumented) apiVersion: 'backstage.io/v1alpha1' | 'backstage.io/v1beta1'; @@ -330,23 +330,23 @@ interface LocationEntityV1alpha1 extends Entity { export { LocationEntityV1alpha1 as LocationEntity }; export { LocationEntityV1alpha1 }; -// @public (undocumented) +// @public export const locationEntityV1alpha1Validator: KindValidator; -// @public @deprecated (undocumented) +// @public @deprecated export const locationSchema: yup.SchemaOf; -// @public (undocumented) +// @public export type LocationSpec = { type: string; target: string; presence?: 'optional' | 'required'; }; -// @public @deprecated (undocumented) +// @public @deprecated export const locationSpecSchema: yup.SchemaOf; -// @public (undocumented) +// @public export function makeValidator(overrides?: Partial): Validators; // @public @@ -356,7 +356,7 @@ export class NoForeignRootFieldsEntityPolicy implements EntityPolicy { enforce(entity: Entity): Promise; } -// @public (undocumented) +// @public export const ORIGIN_LOCATION_ANNOTATION = 'backstage.io/managed-by-origin-location'; @@ -373,13 +373,9 @@ export function parseEntityRef( defaultKind: string; defaultNamespace: string; }, -): { - kind: string; - namespace: string; - name: string; -}; +): EntityName; -// @public (undocumented) +// @public export function parseEntityRef( ref: EntityRef, context?: { @@ -391,7 +387,7 @@ export function parseEntityRef( name: string; }; -// @public (undocumented) +// @public export function parseEntityRef( ref: EntityRef, context?: { @@ -409,28 +405,28 @@ export function parseLocationReference(ref: string): { target: string; }; -// @public (undocumented) +// @public export const RELATION_API_CONSUMED_BY = 'apiConsumedBy'; -// @public (undocumented) +// @public export const RELATION_API_PROVIDED_BY = 'apiProvidedBy'; -// @public (undocumented) +// @public export const RELATION_CHILD_OF = 'childOf'; // @public export const RELATION_CONSUMES_API = 'consumesApi'; -// @public (undocumented) +// @public export const RELATION_DEPENDENCY_OF = 'dependencyOf'; // @public export const RELATION_DEPENDS_ON = 'dependsOn'; -// @public (undocumented) +// @public export const RELATION_HAS_MEMBER = 'hasMember'; -// @public (undocumented) +// @public export const RELATION_HAS_PART = 'hasPart'; // @public @@ -439,7 +435,7 @@ export const RELATION_MEMBER_OF = 'memberOf'; // @public export const RELATION_OWNED_BY = 'ownedBy'; -// @public (undocumented) +// @public export const RELATION_OWNER_OF = 'ownerOf'; // @public @@ -448,10 +444,10 @@ export const RELATION_PARENT_OF = 'parentOf'; // @public export const RELATION_PART_OF = 'partOf'; -// @public (undocumented) +// @public export const RELATION_PROVIDES_API = 'providesApi'; -// @public (undocumented) +// @public interface ResourceEntityV1alpha1 extends Entity { // (undocumented) apiVersion: 'backstage.io/v1alpha1' | 'backstage.io/v1beta1'; @@ -468,7 +464,7 @@ interface ResourceEntityV1alpha1 extends Entity { export { ResourceEntityV1alpha1 as ResourceEntity }; export { ResourceEntityV1alpha1 }; -// @public (undocumented) +// @public export const resourceEntityV1alpha1Validator: KindValidator; // @public @@ -488,7 +484,7 @@ export function serializeEntityRef( }, ): EntityRef; -// @public (undocumented) +// @public export const SOURCE_LOCATION_ANNOTATION = 'backstage.io/source-location'; // @public @@ -508,7 +504,7 @@ export function stringifyLocationReference(ref: { target: string; }): string; -// @public (undocumented) +// @public interface SystemEntityV1alpha1 extends Entity { // (undocumented) apiVersion: 'backstage.io/v1alpha1' | 'backstage.io/v1beta1'; @@ -523,10 +519,10 @@ interface SystemEntityV1alpha1 extends Entity { export { SystemEntityV1alpha1 as SystemEntity }; export { SystemEntityV1alpha1 }; -// @public (undocumented) +// @public export const systemEntityV1alpha1Validator: KindValidator; -// @public (undocumented) +// @public export interface TemplateEntityV1beta2 extends Entity { // (undocumented) apiVersion: 'backstage.io/v1beta2'; @@ -550,7 +546,7 @@ export interface TemplateEntityV1beta2 extends Entity { }; } -// @public (undocumented) +// @public export const templateEntityV1beta2Validator: KindValidator; // @alpha @@ -569,7 +565,7 @@ export type UNSTABLE_EntityStatusItem = { // @alpha export type UNSTABLE_EntityStatusLevel = 'info' | 'warning' | 'error'; -// @public (undocumented) +// @public interface UserEntityV1alpha1 extends Entity { // (undocumented) apiVersion: 'backstage.io/v1alpha1' | 'backstage.io/v1beta1'; @@ -588,10 +584,10 @@ interface UserEntityV1alpha1 extends Entity { export { UserEntityV1alpha1 as UserEntity }; export { UserEntityV1alpha1 }; -// @public (undocumented) +// @public export const userEntityV1alpha1Validator: KindValidator; -// @public (undocumented) +// @public export type Validators = { isValidApiVersion(value: unknown): boolean; isValidKind(value: unknown): boolean; @@ -609,5 +605,5 @@ export const VIEW_URL_ANNOTATION = 'backstage.io/view-url'; // Warnings were encountered during analysis: // -// src/entity/Entity.d.ts:38:5 - (ae-incompatible-release-tags) The symbol "status" is marked as @public, but its signature references "UNSTABLE_EntityStatus" which is marked as @alpha +// src/entity/Entity.d.ts:41:5 - (ae-incompatible-release-tags) The symbol "status" is marked as @public, but its signature references "UNSTABLE_EntityStatus" which is marked as @alpha ``` diff --git a/packages/catalog-model/src/EntityPolicies.ts b/packages/catalog-model/src/EntityPolicies.ts index 0fff68d569..e5aaeb0c20 100644 --- a/packages/catalog-model/src/EntityPolicies.ts +++ b/packages/catalog-model/src/EntityPolicies.ts @@ -52,7 +52,11 @@ class AnyEntityPolicy implements EntityPolicy { } } -/** @public */ +/** + * Provides helpers for enforcing a set of {@link EntityPolicy} in an `and`/`or` expression. + * + * @public + */ export const EntityPolicies = { allOf(policies: EntityPolicy[]): EntityPolicy { return new AllEntityPolicies(policies); diff --git a/packages/catalog-model/src/entity/Entity.ts b/packages/catalog-model/src/entity/Entity.ts index ca38fef183..7a4729c309 100644 --- a/packages/catalog-model/src/entity/Entity.ts +++ b/packages/catalog-model/src/entity/Entity.ts @@ -21,8 +21,11 @@ import { UNSTABLE_EntityStatus } from './EntityStatus'; /** * The parts of the format that's common to all versions/kinds of entity. * + * @remarks + * + * See also: + * {@link https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/} * @public - * @see https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/ */ export type Entity = { /** @@ -63,9 +66,13 @@ export type Entity = { /** * Metadata fields common to all versions/kinds of entity. * + * @remarks + * + * See also: + * {@link https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.18/#objectmeta-v1-meta} + * {@link https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/} + * * @public - * @see https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.18/#objectmeta-v1-meta - * @see https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/ */ export type EntityMeta = JsonObject & { /** diff --git a/packages/catalog-model/src/entity/constants.ts b/packages/catalog-model/src/entity/constants.ts index ff031fc1ae..6daf6b78d9 100644 --- a/packages/catalog-model/src/entity/constants.ts +++ b/packages/catalog-model/src/entity/constants.ts @@ -33,10 +33,15 @@ export const ENTITY_META_GENERATED_FIELDS = [ ] as const; /** - * Annotations for linking to entity from catalog pages. + * Annotation for linking to entity page from catalog pages. * * @public */ export const VIEW_URL_ANNOTATION = 'backstage.io/view-url'; -/** @public */ + +/** + * Annotation for linking to entity edit page from catalog pages. + * + * @public + */ export const EDIT_URL_ANNOTATION = 'backstage.io/edit-url'; diff --git a/packages/catalog-model/src/entity/policies/FieldFormatEntityPolicy.ts b/packages/catalog-model/src/entity/policies/FieldFormatEntityPolicy.ts index b99901b89b..51059328a6 100644 --- a/packages/catalog-model/src/entity/policies/FieldFormatEntityPolicy.ts +++ b/packages/catalog-model/src/entity/policies/FieldFormatEntityPolicy.ts @@ -27,6 +27,8 @@ import { Entity } from '../Entity'; * Ensures that the format of individual fields of the entity envelope * is valid. * + * @remarks + * * This does not take into account machine generated fields such as uid, etag * and generation. * diff --git a/packages/catalog-model/src/entity/policies/SchemaValidEntityPolicy.ts b/packages/catalog-model/src/entity/policies/SchemaValidEntityPolicy.ts index 721dc7d2dc..7f33e71f1c 100644 --- a/packages/catalog-model/src/entity/policies/SchemaValidEntityPolicy.ts +++ b/packages/catalog-model/src/entity/policies/SchemaValidEntityPolicy.ts @@ -24,6 +24,8 @@ import { EntityPolicy } from './types'; /** * Ensures that the entity spec is valid according to a schema. * + * @remarks + * * This should be the first policy in the list, to ensure that other downstream * policies can work with a structure that is at least valid in therms of the * typescript type. diff --git a/packages/catalog-model/src/entity/ref.ts b/packages/catalog-model/src/entity/ref.ts index 6a38e80dfe..958f750e32 100644 --- a/packages/catalog-model/src/entity/ref.ts +++ b/packages/catalog-model/src/entity/ref.ts @@ -69,6 +69,8 @@ export type EntityRefContext = { * Parses an entity reference, either on string or compound form, and always * returns a complete entity name including kind, namespace and name. * + * @remarks + * * This function automatically assumes the default namespace "default" unless * otherwise specified as part of the options, and will throw an error if no * kind was specified in the input reference and no default kind was given. @@ -100,7 +102,9 @@ export function parseEntityName( * Parses an entity reference, either on string or compound form, and returns * a structure with a name, and optional kind and namespace. * - * The options object can contain default values for the kind and namespace, + * @remarks + * + * The context object can contain default values for the kind and namespace, * that will be used if the input reference did not specify any. * * @public @@ -111,12 +115,12 @@ export function parseEntityName( export function parseEntityRef( ref: EntityRef, context?: { defaultKind: string; defaultNamespace: string }, -): { - kind: string; - namespace: string; - name: string; -}; -/** @public */ +): EntityName; +/** + * parseEntityRef with optional Kind. + * + * @public + */ export function parseEntityRef( ref: EntityRef, context?: { defaultKind: string }, @@ -125,7 +129,11 @@ export function parseEntityRef( namespace?: string; name: string; }; -/** @public */ +/** + * parseEntityRef with optional Namespace. + * + * @public + */ export function parseEntityRef( ref: EntityRef, context?: { defaultNamespace: string }, @@ -134,6 +142,11 @@ export function parseEntityRef( namespace: string; name: string; }; +/** + * parseEntityRef with optional Kind and Namespace. + * + * @public + */ export function parseEntityRef( ref: EntityRef, context: EntityRefContext = {}, @@ -223,6 +236,8 @@ export function serializeEntityRef( * Takes an entity or entity name/reference, and returns the string form of an * entity ref. * + * @remarks + * * This function creates a canonical and unique reference to the entity, converting * all parts of the name to lowercase and inserts the default namespace if needed. * It is typically not the best way to represent the entity reference to the user. @@ -256,6 +271,8 @@ export function stringifyEntityRef( /** * Compares an entity to either a string reference or a compound reference. * + * @remarks + * * The comparison is case insensitive, and all of kind, namespace, and name * must match (after applying the optional context to the ref). * diff --git a/packages/catalog-model/src/entity/util.ts b/packages/catalog-model/src/entity/util.ts index 314f3b7737..ce6415afde 100644 --- a/packages/catalog-model/src/entity/util.ts +++ b/packages/catalog-model/src/entity/util.ts @@ -43,6 +43,8 @@ export function generateEntityEtag(): string { * Checks whether there are any significant changes going from the previous to * the next version of this entity. * + * @remarks + * * Significance, in this case, means that we do not compare generated fields * such as uid, etag and generation. * @@ -98,6 +100,8 @@ export function entityHasChanges(previous: Entity, next: Entity): boolean { * Takes an old revision of an entity and a new desired state, and merges * them into a complete new state. * + * @remarks + * * The previous revision is expected to be a complete model loaded from the * catalog, including the uid, etag and generation fields. * diff --git a/packages/catalog-model/src/kinds/ApiEntityV1alpha1.ts b/packages/catalog-model/src/kinds/ApiEntityV1alpha1.ts index 310b6695eb..d733b03c8c 100644 --- a/packages/catalog-model/src/kinds/ApiEntityV1alpha1.ts +++ b/packages/catalog-model/src/kinds/ApiEntityV1alpha1.ts @@ -18,7 +18,15 @@ import type { Entity } from '../entity/Entity'; import schema from '../schema/kinds/API.v1alpha1.schema.json'; import { ajvCompiledJsonSchemaValidator } from './util'; -/** @public */ +/** + * Backstage API kind Entity. APIs describe the interfaces for Components to communicate. + * + * @remarks + * + * See {@link https://backstage.io/docs/features/software-catalog/system-model} + * + * @public + */ export interface ApiEntityV1alpha1 extends Entity { apiVersion: 'backstage.io/v1alpha1' | 'backstage.io/v1beta1'; kind: 'API'; @@ -31,6 +39,10 @@ export interface ApiEntityV1alpha1 extends Entity { }; } -/** @public */ +/** + * {@link KindValidator} for {@link ApiEntityV1alpha1}. + * + * @public + */ export const apiEntityV1alpha1Validator = ajvCompiledJsonSchemaValidator(schema); diff --git a/packages/catalog-model/src/kinds/ComponentEntityV1alpha1.ts b/packages/catalog-model/src/kinds/ComponentEntityV1alpha1.ts index 6777778409..f931eab553 100644 --- a/packages/catalog-model/src/kinds/ComponentEntityV1alpha1.ts +++ b/packages/catalog-model/src/kinds/ComponentEntityV1alpha1.ts @@ -18,7 +18,15 @@ import type { Entity } from '../entity/Entity'; import schema from '../schema/kinds/Component.v1alpha1.schema.json'; import { ajvCompiledJsonSchemaValidator } from './util'; -/** @public */ +/** + * Backstage catalog Component kind Entity. Represents a single, individual piece of software. + * + * @remarks + * + * See {@link https://backstage.io/docs/features/software-catalog/system-model} + * + * @public + */ export interface ComponentEntityV1alpha1 extends Entity { apiVersion: 'backstage.io/v1alpha1' | 'backstage.io/v1beta1'; kind: 'Component'; @@ -34,6 +42,10 @@ export interface ComponentEntityV1alpha1 extends Entity { }; } -/** @public */ +/** + * {@link KindValidator} for {@link ComponentEntityV1alpha1}. + * + * @public + */ export const componentEntityV1alpha1Validator = ajvCompiledJsonSchemaValidator(schema); diff --git a/packages/catalog-model/src/kinds/DomainEntityV1alpha1.ts b/packages/catalog-model/src/kinds/DomainEntityV1alpha1.ts index fe777af24e..e0302fcc52 100644 --- a/packages/catalog-model/src/kinds/DomainEntityV1alpha1.ts +++ b/packages/catalog-model/src/kinds/DomainEntityV1alpha1.ts @@ -18,7 +18,15 @@ import type { Entity } from '../entity/Entity'; import schema from '../schema/kinds/Domain.v1alpha1.schema.json'; import { ajvCompiledJsonSchemaValidator } from './util'; -/** @public */ +/** + * Backstage Domain kind Entity. Domains group Systems together. + * + * @remarks + * + * See {@link https://backstage.io/docs/features/software-catalog/system-model} + * + * @public + */ export interface DomainEntityV1alpha1 extends Entity { apiVersion: 'backstage.io/v1alpha1' | 'backstage.io/v1beta1'; kind: 'Domain'; @@ -27,6 +35,10 @@ export interface DomainEntityV1alpha1 extends Entity { }; } -/** @public */ +/** + * {@link KindValidator} for {@link DomainEntityV1alpha1}. + * + * @public + */ export const domainEntityV1alpha1Validator = ajvCompiledJsonSchemaValidator(schema); diff --git a/packages/catalog-model/src/kinds/GroupEntityV1alpha1.ts b/packages/catalog-model/src/kinds/GroupEntityV1alpha1.ts index f6aab856f0..8d88817dbe 100644 --- a/packages/catalog-model/src/kinds/GroupEntityV1alpha1.ts +++ b/packages/catalog-model/src/kinds/GroupEntityV1alpha1.ts @@ -18,7 +18,11 @@ import type { Entity } from '../entity/Entity'; import schema from '../schema/kinds/Group.v1alpha1.schema.json'; import { ajvCompiledJsonSchemaValidator } from './util'; -/** @public */ +/** + * Backstage catalog Group kind Entity. + * + * @public + */ export interface GroupEntityV1alpha1 extends Entity { apiVersion: 'backstage.io/v1alpha1' | 'backstage.io/v1beta1'; kind: 'Group'; @@ -35,6 +39,9 @@ export interface GroupEntityV1alpha1 extends Entity { }; } -/** @public */ +/** + * {@link KindValidator} for {@link GroupEntityV1alpha1}. + * @public + */ export const groupEntityV1alpha1Validator = ajvCompiledJsonSchemaValidator(schema); diff --git a/packages/catalog-model/src/kinds/LocationEntityV1alpha1.ts b/packages/catalog-model/src/kinds/LocationEntityV1alpha1.ts index f2ae4bcc91..1872e43526 100644 --- a/packages/catalog-model/src/kinds/LocationEntityV1alpha1.ts +++ b/packages/catalog-model/src/kinds/LocationEntityV1alpha1.ts @@ -18,7 +18,11 @@ import type { Entity } from '../entity/Entity'; import schema from '../schema/kinds/Location.v1alpha1.schema.json'; import { ajvCompiledJsonSchemaValidator } from './util'; -/** @public */ +/** + * Backstage catalog Location kind Entity. + * + * @public + */ export interface LocationEntityV1alpha1 extends Entity { apiVersion: 'backstage.io/v1alpha1' | 'backstage.io/v1beta1'; kind: 'Location'; @@ -29,6 +33,10 @@ export interface LocationEntityV1alpha1 extends Entity { }; } -/** @public */ +/** + * {@link KindValidator} for {@link LocationEntityV1alpha1}. + * + * @public + */ export const locationEntityV1alpha1Validator = ajvCompiledJsonSchemaValidator(schema); diff --git a/packages/catalog-model/src/kinds/ResourceEntityV1alpha1.ts b/packages/catalog-model/src/kinds/ResourceEntityV1alpha1.ts index acc6ab5245..0a360cb60b 100644 --- a/packages/catalog-model/src/kinds/ResourceEntityV1alpha1.ts +++ b/packages/catalog-model/src/kinds/ResourceEntityV1alpha1.ts @@ -18,7 +18,15 @@ import type { Entity } from '../entity/Entity'; import schema from '../schema/kinds/Resource.v1alpha1.schema.json'; import { ajvCompiledJsonSchemaValidator } from './util'; -/** @public */ +/** + * Backstage catalog Resource kind Entity. Represents infrastructure required to operate Components. + * + * @remarks + * + * See {@link https://backstage.io/docs/features/software-catalog/system-model} + * + * @public + */ export interface ResourceEntityV1alpha1 extends Entity { apiVersion: 'backstage.io/v1alpha1' | 'backstage.io/v1beta1'; kind: 'Resource'; @@ -30,6 +38,10 @@ export interface ResourceEntityV1alpha1 extends Entity { }; } -/** @public */ +/** + * {@link KindValidator} for {@link ResourceEntityV1alpha1}. + * + * @public + */ export const resourceEntityV1alpha1Validator = ajvCompiledJsonSchemaValidator(schema); diff --git a/packages/catalog-model/src/kinds/SystemEntityV1alpha1.ts b/packages/catalog-model/src/kinds/SystemEntityV1alpha1.ts index 5f90351480..7d1ab703a2 100644 --- a/packages/catalog-model/src/kinds/SystemEntityV1alpha1.ts +++ b/packages/catalog-model/src/kinds/SystemEntityV1alpha1.ts @@ -18,7 +18,15 @@ import type { Entity } from '../entity/Entity'; import schema from '../schema/kinds/System.v1alpha1.schema.json'; import { ajvCompiledJsonSchemaValidator } from './util'; -/** @public */ +/** + * Backstage catalog System kind Entity. Systems group Comopnents, Resources and APIs together. + * + * @remarks + * + * See {@link https://backstage.io/docs/features/software-catalog/system-model} + * + * @public + */ export interface SystemEntityV1alpha1 extends Entity { apiVersion: 'backstage.io/v1alpha1' | 'backstage.io/v1beta1'; kind: 'System'; @@ -28,6 +36,10 @@ export interface SystemEntityV1alpha1 extends Entity { }; } -/** @public */ +/** + * {@link KindValidator} for {@link SystemEntityV1alpha1}. + * + * @public + */ export const systemEntityV1alpha1Validator = ajvCompiledJsonSchemaValidator(schema); diff --git a/packages/catalog-model/src/kinds/TemplateEntityV1beta2.ts b/packages/catalog-model/src/kinds/TemplateEntityV1beta2.ts index e708d4b387..1b1966d05d 100644 --- a/packages/catalog-model/src/kinds/TemplateEntityV1beta2.ts +++ b/packages/catalog-model/src/kinds/TemplateEntityV1beta2.ts @@ -19,7 +19,11 @@ import type { Entity } from '../entity/Entity'; import schema from '../schema/kinds/Template.v1beta2.schema.json'; import { ajvCompiledJsonSchemaValidator } from './util'; -/** @public */ +/** + * Backstage catalog Template kind Entity. Templates are used by the Scaffolder plugin to create new Components. + * + * @public + */ export interface TemplateEntityV1beta2 extends Entity { apiVersion: 'backstage.io/v1beta2'; kind: 'Template'; @@ -38,6 +42,10 @@ export interface TemplateEntityV1beta2 extends Entity { }; } -/** @public */ +/** + * {@link KindValidator} for {@link TemplateEntityV1beta2}. + * + * @public + */ export const templateEntityV1beta2Validator = ajvCompiledJsonSchemaValidator(schema); diff --git a/packages/catalog-model/src/kinds/UserEntityV1alpha1.ts b/packages/catalog-model/src/kinds/UserEntityV1alpha1.ts index d719ab35ef..82aaebd9d6 100644 --- a/packages/catalog-model/src/kinds/UserEntityV1alpha1.ts +++ b/packages/catalog-model/src/kinds/UserEntityV1alpha1.ts @@ -18,7 +18,11 @@ import type { Entity } from '../entity/Entity'; import schema from '../schema/kinds/User.v1alpha1.schema.json'; import { ajvCompiledJsonSchemaValidator } from './util'; -/** @public */ +/** + * Backstage catalog User kind Entity. + * + * @public + */ export interface UserEntityV1alpha1 extends Entity { apiVersion: 'backstage.io/v1alpha1' | 'backstage.io/v1beta1'; kind: 'User'; @@ -32,6 +36,10 @@ export interface UserEntityV1alpha1 extends Entity { }; } -/** @public */ +/** + * {@link KindValidator} for {@link UserEntityV1alpha1}. + * + * @public + */ export const userEntityV1alpha1Validator = ajvCompiledJsonSchemaValidator(schema); diff --git a/packages/catalog-model/src/kinds/relations.ts b/packages/catalog-model/src/kinds/relations.ts index 7546d1508b..4d545c9d35 100644 --- a/packages/catalog-model/src/kinds/relations.ts +++ b/packages/catalog-model/src/kinds/relations.ts @@ -24,61 +24,115 @@ Naming rules for relations in priority order: /** * An ownership relation where the owner is usually an organizational - * entity (user or group), and the other entity can be anything. + * entity (user or group), and the other entity can be anything. Reversed + * direction of {@link RELATION_OWNER_OF}. * * @public */ export const RELATION_OWNED_BY = 'ownedBy'; -/** @public */ + +/** + * A relationship from an owner to the owned entity. Reversed direction of + * {@link RELATION_OWNED_BY}. + * + * @public + */ export const RELATION_OWNER_OF = 'ownerOf'; /** - * A relation with an API entity, typically from a component + * A relation with an API entity, typically from a component. Reversed direction of + * {@link RELATION_API_CONSUMED_BY}. * * @public */ export const RELATION_CONSUMES_API = 'consumesApi'; -/** @public */ + +/** + * A relation of an API being consumed, typically by a component. Reversed direction of + * {@link RELATION_CONSUMES_API}. + * + * @public + */ export const RELATION_API_CONSUMED_BY = 'apiConsumedBy'; -/** @public */ + +/** + * A relation from an API provider entity (typically a component) to the API. Reversed direction of + * {@link RELATION_API_PROVIDED_BY}. + * + * @public + */ export const RELATION_PROVIDES_API = 'providesApi'; -/** @public */ + +/** + * A relation from an API to its provider entity (typically a component). Reversed direction of + * {@link RELATION_PROVIDES_API}. + * + * @public + */ export const RELATION_API_PROVIDED_BY = 'apiProvidedBy'; /** - * A relation denoting a dependency on another entity. + * A relation denoting a dependency on another entity. Reversed direction of + * {@link RELATION_DEPENDENCY_OF}. * * @public */ export const RELATION_DEPENDS_ON = 'dependsOn'; -/** @public */ + +/** + * A relation denoting a reverse dependency by another entity. Reversed direction of + * {@link RELATION_DEPENDS_ON}. + * + * @public + */ export const RELATION_DEPENDENCY_OF = 'dependencyOf'; /** * A parent/child relation to build up a tree, used for example to describe - * the organizational structure between groups. + * the organizational structure between groups. Reversed direction of + * {@link RELATION_CHILD_OF}. * * @public */ export const RELATION_PARENT_OF = 'parentOf'; -/** @public */ + +/** + * A relation from a child to a parent entity, used for example to describe + * the organizational structure between groups. Reversed direction of + * {@link RELATION_PARENT_OF}. + * + * @public + */ export const RELATION_CHILD_OF = 'childOf'; /** - * A membership relation, typically for users in a group. + * A membership relation, typically for users in a group. Reversed direction of + * {@link RELATION_HAS_MEMBER}. * * @public */ export const RELATION_MEMBER_OF = 'memberOf'; -/** @public */ + +/** + * A relation from a group to its member, typcally a user in a group. Reversed direction of + * {@link RELATION_MEMBER_OF}. + * + * @public + */ export const RELATION_HAS_MEMBER = 'hasMember'; /** * A part/whole relation, typically for components in a system and systems - * in a domain. + * in a domain. Reversed direction of {@link RELATION_HAS_PART}. * * @public */ export const RELATION_PART_OF = 'partOf'; -/** @public */ + +/** + * A relation from a containing entity to a contained entity. Reversed direction of + * {@link RELATION_PART_OF}. + * + * @public + */ export const RELATION_HAS_PART = 'hasPart'; diff --git a/packages/catalog-model/src/location/annotation.ts b/packages/catalog-model/src/location/annotation.ts index 4bcabdb705..8eb393f555 100644 --- a/packages/catalog-model/src/location/annotation.ts +++ b/packages/catalog-model/src/location/annotation.ts @@ -14,11 +14,20 @@ * limitations under the License. */ -/** @public */ +/** + * Constant storing location annotation. + * + * @public */ export const LOCATION_ANNOTATION = 'backstage.io/managed-by-location'; -/** @public */ +/** + * Constant storing origin location annotation + * + * @public */ export const ORIGIN_LOCATION_ANNOTATION = 'backstage.io/managed-by-origin-location'; -/** @public */ +/** + * Contant storing source location annotation + * + * @public */ export const SOURCE_LOCATION_ANNOTATION = 'backstage.io/source-location'; diff --git a/packages/catalog-model/src/location/helpers.ts b/packages/catalog-model/src/location/helpers.ts index cf12031dc1..1edd4e5ec5 100644 --- a/packages/catalog-model/src/location/helpers.ts +++ b/packages/catalog-model/src/location/helpers.ts @@ -65,6 +65,8 @@ export function parseLocationReference(ref: string): { /** * Turns a location reference into its string form. * + * @remarks + * * Note that the input type is not `LocationSpec`, because we do not want to * conflate the string form with the additional properties of that type. * @@ -90,6 +92,8 @@ export function stringifyLocationReference(ref: { /** * Returns the source code location of the Entity, to the extent that one exists. * + * @remarks + * * If the returned location type is of type 'url', the target should be readable at least * using the UrlReader from `@backstage/backend-common`. If it is not of type 'url', the caller * needs to have explicit handling of each location type or signal that it is not supported. diff --git a/packages/catalog-model/src/location/types.ts b/packages/catalog-model/src/location/types.ts index 1d16a9047d..725f873f2d 100644 --- a/packages/catalog-model/src/location/types.ts +++ b/packages/catalog-model/src/location/types.ts @@ -14,17 +14,28 @@ * limitations under the License. */ -/** @public */ +/** + * Holds the entity location information. + * + * @remarks + * + * `presence` flag: when using repo importer plugin, location is being created before the component yaml file is merged to the main branch. + * This flag is then set to indicate that the file can be not present. + * default value: 'required'. + * + * @public + */ export type LocationSpec = { type: string; target: string; - // When using repo importer plugin, location is being created before the component yaml file is merged to the main branch. - // This flag is then set to indicate that the file can be not present. - // default value: 'required'. presence?: 'optional' | 'required'; }; -/** @public */ +/** + * Entity location for a specific entity. + * + * @public + */ export type Location = { id: string; } & LocationSpec; diff --git a/packages/catalog-model/src/location/validation.ts b/packages/catalog-model/src/location/validation.ts index 452c69af53..2fd692e649 100644 --- a/packages/catalog-model/src/location/validation.ts +++ b/packages/catalog-model/src/location/validation.ts @@ -18,8 +18,10 @@ import * as yup from 'yup'; import { LocationSpec, Location } from './types'; /** + * Deprecated. + * * @public - * @deprecated Use JSONSchema or validators instead. + * @deprecated Use {@link JSONSchema} or validators instead. */ export const locationSpecSchema: yup.SchemaOf = yup .object({ @@ -31,8 +33,10 @@ export const locationSpecSchema: yup.SchemaOf = yup .required(); /** + * Deprecated. + * * @public - * @deprecated Use JSONSchema or validators instead. + * @deprecated Use {@link JSONSchema} or validators instead. */ export const locationSchema: yup.SchemaOf = yup .object({ @@ -45,8 +49,10 @@ export const locationSchema: yup.SchemaOf = yup .required(); /** + * Deprecated. + * * @public - * @deprecated Use JSONSchema or validators instead. + * @deprecated Use {@link JSONSchema} or validators instead. */ export const analyzeLocationSchema: yup.SchemaOf<{ location: LocationSpec }> = yup diff --git a/packages/catalog-model/src/types.ts b/packages/catalog-model/src/types.ts index 1fbb3be95c..8ec1303a40 100644 --- a/packages/catalog-model/src/types.ts +++ b/packages/catalog-model/src/types.ts @@ -17,7 +17,11 @@ import { JsonValue } from '@backstage/config'; import { JSONSchema7 } from 'json-schema'; -/** @public */ +/** + * JSONSchema extendable by arbitrary JSON attributes + * + * @public + */ export type JSONSchema = JSONSchema7 & { [key in string]?: JsonValue }; /** @@ -35,7 +39,9 @@ export type EntityName = { * A reference by name to an entity, either as a compact string representation, * or as a compound reference structure. * - * The string representation is on the form [:][/]. + * @remarks + * + * The string representation is on the form `[:][/]`. * * Left-out parts of the reference need to be handled by the application, * either by rejecting the reference or by falling back to default values. diff --git a/packages/catalog-model/src/validation/entityEnvelopeSchemaValidator.ts b/packages/catalog-model/src/validation/entityEnvelopeSchemaValidator.ts index daa44ffaf1..a2a8ba64b7 100644 --- a/packages/catalog-model/src/validation/entityEnvelopeSchemaValidator.ts +++ b/packages/catalog-model/src/validation/entityEnvelopeSchemaValidator.ts @@ -25,6 +25,8 @@ import { compileAjvSchema, throwAjvError } from './ajv'; * if it matches that schema, or throws a {@link globals#TypeError} describing the * errors. * + * @remarks + * * Note that this validator is only meant for applying the base schema checks; * it does not take custom policies or additional processor based validation * into account. @@ -33,13 +35,15 @@ import { compileAjvSchema, throwAjvError } from './ajv'; * own, it may contain `$ref` references to the following, which are resolved * automatically for you: * - * - EntityEnvelope - * - Entity - * - EntityMeta - * - common# + * - {@link EntityEnvelope} + * - {@link Entity} + * - {@link EntityMeta} + * - `common#` + * + * See also {@link https://github.com/backstage/backstage/tree/master/packages/catalog-model/src/schema} * * @public - * @see https://github.com/backstage/backstage/tree/master/packages/catalog-model/src/schema + * */ export function entityEnvelopeSchemaValidator< T extends EntityEnvelope = EntityEnvelope, diff --git a/packages/catalog-model/src/validation/entityKindSchemaValidator.ts b/packages/catalog-model/src/validation/entityKindSchemaValidator.ts index 535dba9842..66259cc63d 100644 --- a/packages/catalog-model/src/validation/entityKindSchemaValidator.ts +++ b/packages/catalog-model/src/validation/entityKindSchemaValidator.ts @@ -24,6 +24,8 @@ import { compileAjvSchema, throwAjvError } from './ajv'; * schema apiVersion/kind didn't apply to that data, or throws a * {@link globals#TypeError} describing actual errors. * + * @remarks + * * This validator is highly specialized, in that it has special treatment of * the `kind` and `apiVersion` root keys. This only works if your schema has * their rule set to `"enum"`: @@ -47,13 +49,16 @@ import { compileAjvSchema, throwAjvError } from './ajv'; * The given schema may contain `$ref` references to the following, which are * resolved automatically for you: * - * - EntityEnvelope - * - Entity - * - EntityMeta - * - common# + * - {@link Entity} + * + * - {@link EntityEnvelope} + * + * - {@link EntityMeta} + * + * - `common#` + * @see {@link https://github.com/backstage/backstage/tree/master/packages/catalog-model/src/schema} * * @public - * @see https://github.com/backstage/backstage/tree/master/packages/catalog-model/src/schema */ export function entityKindSchemaValidator( schema: unknown, diff --git a/packages/catalog-model/src/validation/entitySchemaValidator.ts b/packages/catalog-model/src/validation/entitySchemaValidator.ts index dd110efd75..fc1918e566 100644 --- a/packages/catalog-model/src/validation/entitySchemaValidator.ts +++ b/packages/catalog-model/src/validation/entitySchemaValidator.ts @@ -24,21 +24,23 @@ import { compileAjvSchema, throwAjvError } from './ajv'; * returns that data cast to an {@link Entity} (or the given subtype) if it * matches that schema, or throws a {@link globals#TypeError} describing the errors. * + * @remarks + * * Note that this validator is only meant for applying the base schema checks; * it does not take custom policies or additional processor based validation * into account. * - * By default, the plain `Entity` schema is used. If you pass in your own, it + * By default, the plain {@link Entity} schema is used. If you pass in your own, it * may contain `$ref` references to the following, which are resolved * automatically for you: * - * - EntityEnvelope - * - Entity - * - EntityMeta - * - common# + * - {@link Entity} + * - {@link EntityEnvelope} + * - {@link EntityMeta} + * - `common#` * * @public - * @see https://github.com/backstage/backstage/tree/master/packages/catalog-model/src/schema + * @see {@link https://github.com/backstage/backstage/tree/master/packages/catalog-model/src/schema} */ export function entitySchemaValidator( schema?: unknown, diff --git a/packages/catalog-model/src/validation/makeValidator.ts b/packages/catalog-model/src/validation/makeValidator.ts index bd6dccc419..ad3f52e563 100644 --- a/packages/catalog-model/src/validation/makeValidator.ts +++ b/packages/catalog-model/src/validation/makeValidator.ts @@ -30,7 +30,11 @@ const defaultValidators: Validators = { isValidTag: CommonValidatorFunctions.isValidTag, }; -/** @public */ +/** + * Creates a {@link Validators} object from `overrides`, with default values taken from {@link KubernetesValidatorFunctions} + * + * @public + */ export function makeValidator(overrides: Partial = {}): Validators { return { ...defaultValidators, diff --git a/packages/catalog-model/src/validation/types.ts b/packages/catalog-model/src/validation/types.ts index 23d639c166..e3615e6a83 100644 --- a/packages/catalog-model/src/validation/types.ts +++ b/packages/catalog-model/src/validation/types.ts @@ -14,7 +14,11 @@ * limitations under the License. */ -/** @public */ +/** + * Type alias for implementing validators of various entity objects. + * + * @public + */ export type Validators = { isValidApiVersion(value: unknown): boolean; isValidKind(value: unknown): boolean; diff --git a/packages/cli/config/jestEsmTransform.js b/packages/cli/config/jestEsmTransform.js new file mode 100644 index 0000000000..c1eec7d9f8 --- /dev/null +++ b/packages/cli/config/jestEsmTransform.js @@ -0,0 +1,19 @@ +/* + * Copyright 2021 The Backstage Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +throw new Error( + 'The ./jestEsmTransform.js transform has been removed, switch to using ./jestSucraseTransform.js instead', +); diff --git a/packages/cli/package.json b/packages/cli/package.json index ecc3d3b4e1..ebd8f0169c 100644 --- a/packages/cli/package.json +++ b/packages/cli/package.json @@ -31,6 +31,7 @@ "@backstage/cli-common": "^0.1.4", "@backstage/config": "^0.1.10", "@backstage/config-loader": "^0.6.10", + "@backstage/errors": "^0.1.2", "@hot-loader/react-dom": "^16.13.0", "@lerna/package-graph": "^4.0.0", "@lerna/project": "^4.0.0", diff --git a/packages/cli/src/commands/create-plugin/createPlugin.ts b/packages/cli/src/commands/create-plugin/createPlugin.ts index 6ddd1f7160..a5ea565cae 100644 --- a/packages/cli/src/commands/create-plugin/createPlugin.ts +++ b/packages/cli/src/commands/create-plugin/createPlugin.ts @@ -24,6 +24,7 @@ import camelCase from 'lodash/camelCase'; import upperFirst from 'lodash/upperFirst'; import os from 'os'; import { Command } from 'commander'; +import { assertError } from '@backstage/errors'; import { parseOwnerIds, addCodeownersEntry, @@ -173,6 +174,7 @@ async function buildPlugin(pluginFolder: string) { ); }); } catch (error) { + assertError(error); Task.error(error.message); break; } @@ -329,6 +331,7 @@ export default async (cmd: Command) => { Task.log(); Task.exit(); } catch (error) { + assertError(error); Task.error(error.message); Task.log('It seems that something went wrong when creating the plugin πŸ€”'); diff --git a/packages/cli/src/commands/index.ts b/packages/cli/src/commands/index.ts index d6686f2655..302f76cc5d 100644 --- a/packages/cli/src/commands/index.ts +++ b/packages/cli/src/commands/index.ts @@ -14,6 +14,7 @@ * limitations under the License. */ +import { assertError } from '@backstage/errors'; import { CommanderStatic } from 'commander'; import { exitWithError } from '../lib/errors'; @@ -252,6 +253,7 @@ function lazy( process.exit(0); } catch (error) { + assertError(error); exitWithError(error); } }; diff --git a/packages/cli/src/commands/remove-plugin/removePlugin.ts b/packages/cli/src/commands/remove-plugin/removePlugin.ts index 9e1e18bb7b..11fdc8bb11 100644 --- a/packages/cli/src/commands/remove-plugin/removePlugin.ts +++ b/packages/cli/src/commands/remove-plugin/removePlugin.ts @@ -20,6 +20,7 @@ import inquirer, { Answers, Question } from 'inquirer'; import { getCodeownersFilePath } from '../../lib/codeowners'; import { paths } from '../../lib/paths'; import { Task } from '../../lib/tasks'; +import { assertError } from '@backstage/errors'; const BACKSTAGE = '@backstage'; @@ -35,6 +36,7 @@ export const checkExists = async (rootDir: string, pluginName: string) => { ); } } catch (e) { + assertError(e); throw new Error( chalk.red( ` There was an error removing plugin ${chalk.cyan(pluginName)}: ${ @@ -51,6 +53,7 @@ export const removePluginDirectory = async (destination: string) => { try { await fse.remove(destination); } catch (e) { + assertError(e); throw Error( chalk.red( ` There was a problem removing the plugin directory: ${e.message}`, @@ -67,6 +70,7 @@ export const removeSymLink = async (destination: string) => { try { await fse.remove(destination); } catch (e) { + assertError(e); throw Error( chalk.red( ` Could not remove symbolic link\t${chalk.cyan(destination)}: ${ @@ -106,6 +110,7 @@ export const removeReferencesFromPluginsFile = async ( try { await removeAllStatementsContainingID(pluginsFile, pluginNameCapitalized); } catch (e) { + assertError(e); throw new Error( chalk.red( ` There was an error removing export statement for plugin ${chalk.cyan( @@ -125,6 +130,7 @@ export const removePluginFromCodeOwners = async ( try { await removeAllStatementsContainingID(codeOwnersFile, pluginName); } catch (e) { + assertError(e); throw new Error( chalk.red( ` There was an error removing code owners statement for plugin ${chalk.cyan( @@ -165,6 +171,7 @@ export const removeReferencesFromAppPackage = async ( 'utf-8', ); } catch (e) { + assertError(e); throw new Error( chalk.red( ` Failed to remove plugin as dependency in app: ${chalk.cyan( @@ -245,6 +252,7 @@ export default async () => { ); Task.log(); } catch (error) { + assertError(error); Task.error(error.message); Task.log('It seems that something went wrong when removing the plugin πŸ€”'); } diff --git a/packages/cli/src/commands/versions/bump.ts b/packages/cli/src/commands/versions/bump.ts index 257a83e2be..7b967839b2 100644 --- a/packages/cli/src/commands/versions/bump.ts +++ b/packages/cli/src/commands/versions/bump.ts @@ -17,6 +17,7 @@ import fs from 'fs-extra'; import chalk from 'chalk'; import semver from 'semver'; +import { isError } from '@backstage/errors'; import { resolve as resolvePath } from 'path'; import { run } from '../../lib/run'; import { paths } from '../../lib/paths'; @@ -59,7 +60,7 @@ export default async () => { try { target = await findTargetVersion(name); } catch (error) { - if (error.name === 'NotFoundError') { + if (isError(error) && error.name === 'NotFoundError') { console.log(`Package info not found, ignoring package ${name}`); return; } @@ -97,7 +98,7 @@ export default async () => { try { target = await findTargetVersion(name); } catch (error) { - if (error.name === 'NotFoundError') { + if (isError(error) && error.name === 'NotFoundError') { console.log(`Package info not found, ignoring package ${name}`); return; } diff --git a/packages/cli/src/lib/run.ts b/packages/cli/src/lib/run.ts index 7cf22a6df9..4efb791c30 100644 --- a/packages/cli/src/lib/run.ts +++ b/packages/cli/src/lib/run.ts @@ -23,6 +23,7 @@ import { import { ExitCodeError } from './errors'; import { promisify } from 'util'; import { LogFunc } from './logging'; +import { assertError, ForwardedError } from '@backstage/errors'; const execFile = promisify(execFileCb); @@ -75,10 +76,14 @@ export async function runPlain(cmd: string, ...args: string[]) { const { stdout } = await execFile(cmd, args, { shell: true }); return stdout.trim(); } catch (error) { - if (error.stderr) { - process.stderr.write(error.stderr); + assertError(error); + if ('stderr' in error) { + process.stderr.write(error.stderr as Buffer); } - throw new ExitCodeError(error.code, [cmd, ...args].join(' ')); + if (typeof error.code === 'number') { + throw new ExitCodeError(error.code, [cmd, ...args].join(' ')); + } + throw new ForwardedError('Unknown execution error', error); } } diff --git a/packages/config-loader/api-report.md b/packages/config-loader/api-report.md index 355839c5af..b47119d470 100644 --- a/packages/config-loader/api-report.md +++ b/packages/config-loader/api-report.md @@ -26,18 +26,15 @@ export type ConfigSchemaProcessingOptions = { // @public export type ConfigVisibility = 'frontend' | 'backend' | 'secret'; -// @public (undocumented) -export type EnvFunc = (name: string) => Promise; - // @public export function loadConfig(options: LoadConfigOptions): Promise; -// @public (undocumented) +// @public export type LoadConfigOptions = { configRoot: string; configPaths: string[]; env?: string; - experimentalEnvFunc?: EnvFunc; + experimentalEnvFunc?: (name: string) => Promise; watch?: { onChange: (configs: AppConfig[]) => void; stopSignal?: Promise; @@ -49,7 +46,7 @@ export function loadConfigSchema( options: LoadConfigSchemaOptions, ): Promise; -// @public (undocumented) +// @public export type LoadConfigSchemaOptions = | { dependencies: string[]; diff --git a/packages/config-loader/package.json b/packages/config-loader/package.json index a719c6389b..ebca3ffdf3 100644 --- a/packages/config-loader/package.json +++ b/packages/config-loader/package.json @@ -32,6 +32,7 @@ "dependencies": { "@backstage/cli-common": "^0.1.4", "@backstage/config": "^0.1.9", + "@backstage/errors": "^0.1.2", "@types/json-schema": "^7.0.6", "ajv": "^7.0.3", "chokidar": "^3.5.2", diff --git a/packages/config-loader/src/index.ts b/packages/config-loader/src/index.ts index 0e66c59ec4..888c68ef70 100644 --- a/packages/config-loader/src/index.ts +++ b/packages/config-loader/src/index.ts @@ -25,7 +25,6 @@ export type { ConfigSchema, ConfigSchemaProcessingOptions, ConfigVisibility, - EnvFunc, LoadConfigSchemaOptions, TransformFunc, } from './lib'; diff --git a/packages/config-loader/src/lib/env.ts b/packages/config-loader/src/lib/env.ts index b244c06c64..57cfc077a7 100644 --- a/packages/config-loader/src/lib/env.ts +++ b/packages/config-loader/src/lib/env.ts @@ -15,6 +15,7 @@ */ import { AppConfig, JsonObject } from '@backstage/config'; +import { assertError } from '@backstage/errors'; const ENV_PREFIX = 'APP_CONFIG_'; @@ -96,6 +97,7 @@ function safeJsonParse(str: string): [Error | null, any] { try { return [null, JSON.parse(str)]; } catch (err) { + assertError(err); return [err, str]; } } diff --git a/packages/config-loader/src/lib/schema/collect.ts b/packages/config-loader/src/lib/schema/collect.ts index f8b134119b..de6aff376f 100644 --- a/packages/config-loader/src/lib/schema/collect.ts +++ b/packages/config-loader/src/lib/schema/collect.ts @@ -24,6 +24,7 @@ import { import { ConfigSchemaPackageEntry } from './types'; import { getProgramFromFiles, generateSchema } from 'typescript-json-schema'; import { JsonObject } from '@backstage/config'; +import { assertError } from '@backstage/errors'; type Item = { name?: string; @@ -189,6 +190,7 @@ function compileTsSchemas(paths: string[]) { [path.split(sep).join('/')], // Unix paths are expected for all OSes here ) as JsonObject | null; } catch (error) { + assertError(error); if (error.message !== 'type Config not found') { throw error; } diff --git a/packages/config-loader/src/lib/schema/load.ts b/packages/config-loader/src/lib/schema/load.ts index 0e9ddabcb3..f3ea0b900e 100644 --- a/packages/config-loader/src/lib/schema/load.ts +++ b/packages/config-loader/src/lib/schema/load.ts @@ -25,7 +25,11 @@ import { CONFIG_VISIBILITIES, } from './types'; -/** @public */ +/** + * Options that control the loading of configuration schema files in the backend. + * + * @public + */ export type LoadConfigSchemaOptions = | { dependencies: string[]; diff --git a/packages/config-loader/src/lib/transform/apply.ts b/packages/config-loader/src/lib/transform/apply.ts index 690d280266..091f9c23c5 100644 --- a/packages/config-loader/src/lib/transform/apply.ts +++ b/packages/config-loader/src/lib/transform/apply.ts @@ -15,6 +15,7 @@ */ import { JsonObject, JsonValue } from '@backstage/config'; +import { assertError } from '@backstage/errors'; import { TransformFunc } from './types'; import { isObject } from './utils'; @@ -46,6 +47,7 @@ export async function applyConfigTransforms( break; } } catch (error) { + assertError(error); throw new Error(`error at ${path}, ${error.message}`); } } diff --git a/packages/config-loader/src/lib/transform/index.ts b/packages/config-loader/src/lib/transform/index.ts index eaa85cca3c..5053cd7443 100644 --- a/packages/config-loader/src/lib/transform/index.ts +++ b/packages/config-loader/src/lib/transform/index.ts @@ -17,4 +17,3 @@ export { applyConfigTransforms } from './apply'; export { createIncludeTransform } from './include'; export { createSubstitutionTransform } from './substitution'; -export type { EnvFunc } from './types'; diff --git a/packages/config-loader/src/lib/transform/types.ts b/packages/config-loader/src/lib/transform/types.ts index afd3550984..20e5f88718 100644 --- a/packages/config-loader/src/lib/transform/types.ts +++ b/packages/config-loader/src/lib/transform/types.ts @@ -16,7 +16,6 @@ import { JsonValue } from '@backstage/config'; -/** @public */ export type EnvFunc = (name: string) => Promise; export type ReadFileFunc = (path: string) => Promise; diff --git a/packages/config-loader/src/loader.ts b/packages/config-loader/src/loader.ts index 315b44c4ee..6803d61786 100644 --- a/packages/config-loader/src/loader.ts +++ b/packages/config-loader/src/loader.ts @@ -19,15 +19,19 @@ import yaml from 'yaml'; import chokidar from 'chokidar'; import { resolve as resolvePath, dirname, isAbsolute, basename } from 'path'; import { AppConfig } from '@backstage/config'; +import { ForwardedError } from '@backstage/errors'; import { applyConfigTransforms, readEnvConfig, createIncludeTransform, createSubstitutionTransform, } from './lib'; -import { EnvFunc } from './lib/transform/types'; -/** @public */ +/** + * Options that control the loading of configuration files in the backend. + * + * @public + */ export type LoadConfigOptions = { // The root directory of the config loading context. Used to find default configs. configRoot: string; @@ -43,7 +47,7 @@ export type LoadConfigOptions = { * * @experimental This API is not stable and may change at any point */ - experimentalEnvFunc?: EnvFunc; + experimentalEnvFunc?: (name: string) => Promise; /** * An optional configuration that enables watching of config files. @@ -114,9 +118,7 @@ export async function loadConfig( try { fileConfigs = await loadConfigFiles(); } catch (error) { - throw new Error( - `Failed to read static configuration file, ${error.message}`, - ); + throw new ForwardedError('Failed to read static configuration file', error); } const envConfigs = await readEnvConfig(process.env); diff --git a/packages/core-app-api/api-report.md b/packages/core-app-api/api-report.md index 22d5092aa6..869f9a6eb0 100644 --- a/packages/core-app-api/api-report.md +++ b/packages/core-app-api/api-report.md @@ -15,6 +15,7 @@ import { ApiRef } from '@backstage/core-plugin-api'; import { AppConfig } from '@backstage/config'; import { AppTheme } from '@backstage/core-plugin-api'; import { AppThemeApi } from '@backstage/core-plugin-api'; +import { atlassianAuthApiRef } from '@backstage/core-plugin-api'; import { auth0AuthApiRef } from '@backstage/core-plugin-api'; import { AuthProvider } from '@backstage/core-plugin-api'; import { AuthRequester } from '@backstage/core-plugin-api'; @@ -236,12 +237,25 @@ export class AppThemeSelector implements AppThemeApi { setActiveThemeId(themeId?: string): void; } +// Warning: (ae-missing-release-tag) "AtlassianAuth" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) +// +// @public (undocumented) +export class AtlassianAuth { + // Warning: (ae-forgotten-export) The symbol "OAuthApiCreateOptions" needs to be exported by the entry point index.d.ts + // + // (undocumented) + static create({ + discoveryApi, + environment, + provider, + oauthRequestApi, + }: OAuthApiCreateOptions): typeof atlassianAuthApiRef.T; +} + // Warning: (ae-missing-release-tag) "Auth0Auth" is exported by the package, but it is missing a release tag (@alpha, @beta, @public, or @internal) // // @public (undocumented) export class Auth0Auth { - // Warning: (ae-forgotten-export) The symbol "OAuthApiCreateOptions" needs to be exported by the entry point index.d.ts - // // (undocumented) static create({ discoveryApi, diff --git a/packages/core-app-api/src/apis/implementations/DiscoveryApi/UrlPatternDiscovery.test.ts b/packages/core-app-api/src/apis/implementations/DiscoveryApi/UrlPatternDiscovery.test.ts index 9cd666e8a3..7fcbde97df 100644 --- a/packages/core-app-api/src/apis/implementations/DiscoveryApi/UrlPatternDiscovery.test.ts +++ b/packages/core-app-api/src/apis/implementations/DiscoveryApi/UrlPatternDiscovery.test.ts @@ -45,25 +45,25 @@ describe('UrlPatternDiscovery', () => { it('should validate that the pattern is a valid URL', () => { expect(() => { UrlPatternDiscovery.compile('example.com'); - }).toThrow('Invalid discovery URL pattern, Invalid URL: example.com'); + }).toThrow("Invalid discovery URL pattern, URL 'example.com' is invalid"); expect(() => { UrlPatternDiscovery.compile('http://'); - }).toThrow('Invalid discovery URL pattern, Invalid URL: http://'); + }).toThrow("Invalid discovery URL pattern, URL 'http://' is invalid"); expect(() => { UrlPatternDiscovery.compile('abc123'); - }).toThrow('Invalid discovery URL pattern, Invalid URL: abc123'); + }).toThrow("Invalid discovery URL pattern, URL 'abc123' is invalid"); expect(() => { UrlPatternDiscovery.compile('http://example.com:{{pluginId}}'); }).toThrow( - 'Invalid discovery URL pattern, Invalid URL: http://example.com:pluginId', + "Invalid discovery URL pattern, URL 'http://example.com:pluginId' is invalid", ); expect(() => { UrlPatternDiscovery.compile('/{{pluginId}}'); - }).toThrow('Invalid discovery URL pattern, Invalid URL: /pluginId'); + }).toThrow("Invalid discovery URL pattern, URL '/pluginId' is invalid"); expect(() => { UrlPatternDiscovery.compile('http://localhost/{{pluginId}}?forbidden'); diff --git a/packages/core-app-api/src/apis/implementations/DiscoveryApi/UrlPatternDiscovery.ts b/packages/core-app-api/src/apis/implementations/DiscoveryApi/UrlPatternDiscovery.ts index 81cc5a26b1..58e14c9f04 100644 --- a/packages/core-app-api/src/apis/implementations/DiscoveryApi/UrlPatternDiscovery.ts +++ b/packages/core-app-api/src/apis/implementations/DiscoveryApi/UrlPatternDiscovery.ts @@ -16,6 +16,8 @@ import { DiscoveryApi } from '@backstage/core-plugin-api'; +const ERROR_PREFIX = 'Invalid discovery URL pattern,'; + /** * UrlPatternDiscovery is a lightweight DiscoveryApi implementation. * It uses a single template string to construct URLs for each plugin. @@ -30,21 +32,22 @@ export class UrlPatternDiscovery implements DiscoveryApi { */ static compile(pattern: string): UrlPatternDiscovery { const parts = pattern.split(/\{\{\s*pluginId\s*\}\}/); + const urlStr = parts.join('pluginId'); + let url; try { - const urlStr = parts.join('pluginId'); - const url = new URL(urlStr); - if (url.hash) { - throw new Error('URL must not have a hash'); - } - if (url.search) { - throw new Error('URL must not have a query'); - } - if (urlStr.endsWith('/')) { - throw new Error('URL must not end with a slash'); - } - } catch (error) { - throw new Error(`Invalid discovery URL pattern, ${error.message}`); + url = new URL(urlStr); + } catch { + throw new Error(`${ERROR_PREFIX} URL '${urlStr}' is invalid`); + } + if (url.hash) { + throw new Error(`${ERROR_PREFIX} URL must not have a hash`); + } + if (url.search) { + throw new Error(`${ERROR_PREFIX} URL must not have a query`); + } + if (urlStr.endsWith('/')) { + throw new Error(`${ERROR_PREFIX} URL must not end with a slash`); } return new UrlPatternDiscovery(parts); diff --git a/packages/core-app-api/src/apis/implementations/auth/atlassian/AtlassianAuth.ts b/packages/core-app-api/src/apis/implementations/auth/atlassian/AtlassianAuth.ts new file mode 100644 index 0000000000..423c45bc6c --- /dev/null +++ b/packages/core-app-api/src/apis/implementations/auth/atlassian/AtlassianAuth.ts @@ -0,0 +1,44 @@ +/* + * Copyright 2020 The Backstage Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +import AtlassianIcon from '@material-ui/icons/AcUnit'; +import { atlassianAuthApiRef } from '@backstage/core-plugin-api'; +import { OAuth2 } from '../oauth2'; +import { OAuthApiCreateOptions } from '../types'; + +const DEFAULT_PROVIDER = { + id: 'atlassian', + title: 'Atlassian', + icon: AtlassianIcon, +}; + +class AtlassianAuth { + static create({ + discoveryApi, + environment = 'development', + provider = DEFAULT_PROVIDER, + oauthRequestApi, + }: OAuthApiCreateOptions): typeof atlassianAuthApiRef.T { + return OAuth2.create({ + discoveryApi, + oauthRequestApi, + provider, + environment, + }); + } +} + +export default AtlassianAuth; diff --git a/packages/techdocs-common/__mocks__/globals.d.ts b/packages/core-app-api/src/apis/implementations/auth/atlassian/index.ts similarity index 84% rename from packages/techdocs-common/__mocks__/globals.d.ts rename to packages/core-app-api/src/apis/implementations/auth/atlassian/index.ts index ad293d2ebe..fb787be1ce 100644 --- a/packages/techdocs-common/__mocks__/globals.d.ts +++ b/packages/core-app-api/src/apis/implementations/auth/atlassian/index.ts @@ -14,9 +14,4 @@ * limitations under the License. */ -declare module NodeJS { - interface Global { - rootDir: string; - storageFilesMock: IStorageFilesMock; - } -} +export { default as AtlassianAuth } from './AtlassianAuth'; diff --git a/packages/core-app-api/src/apis/implementations/auth/index.ts b/packages/core-app-api/src/apis/implementations/auth/index.ts index b622b90b8c..bbc9d23ccc 100644 --- a/packages/core-app-api/src/apis/implementations/auth/index.ts +++ b/packages/core-app-api/src/apis/implementations/auth/index.ts @@ -24,3 +24,4 @@ export * from './auth0'; export * from './microsoft'; export * from './onelogin'; export * from './bitbucket'; +export * from './atlassian'; diff --git a/packages/core-app-api/src/app/defaultApis.ts b/packages/core-app-api/src/app/defaultApis.ts index 5e850f4cce..fb02274cf0 100644 --- a/packages/core-app-api/src/app/defaultApis.ts +++ b/packages/core-app-api/src/app/defaultApis.ts @@ -33,6 +33,7 @@ import { SamlAuth, OneLoginAuth, UnhandledErrorForwarder, + AtlassianAuth, } from '../apis'; import { @@ -55,6 +56,7 @@ import { oneloginAuthApiRef, oidcAuthApiRef, bitbucketAuthApiRef, + atlassianAuthApiRef, } from '@backstage/core-plugin-api'; import OAuth2Icon from '@material-ui/icons/AcUnit'; @@ -244,4 +246,19 @@ export const defaultApis = [ environment: configApi.getOptionalString('auth.environment'), }), }), + createApiFactory({ + api: atlassianAuthApiRef, + deps: { + discoveryApi: discoveryApiRef, + oauthRequestApi: oauthRequestApiRef, + configApi: configApiRef, + }, + factory: ({ discoveryApi, oauthRequestApi, configApi }) => { + return AtlassianAuth.create({ + discoveryApi, + oauthRequestApi, + environment: configApi.getOptionalString('auth.environment'), + }); + }, + }), ]; diff --git a/packages/core-app-api/src/routing/RoutingProvider.test.tsx b/packages/core-app-api/src/routing/RoutingProvider.test.tsx index 12d9e9ee33..fbdd34ae68 100644 --- a/packages/core-app-api/src/routing/RoutingProvider.test.tsx +++ b/packages/core-app-api/src/routing/RoutingProvider.test.tsx @@ -83,7 +83,7 @@ const MockRouteSource = (props: { } catch (ex) { return (
- Error at {props.name}: {ex.message} + Error at {props.name}, {String(ex)}
); } @@ -293,12 +293,12 @@ describe('discovery', () => { expect( rendered.getByText( - `Error at outsideWithParams: Cannot route to ${ref3} with parent ${ref5} as it has parameters`, + `Error at outsideWithParams, Error: Cannot route to ${ref3} with parent ${ref5} as it has parameters`, ), ).toBeInTheDocument(); expect( rendered.getByText( - `Error at outsideNoParams: Cannot route to ${ref3} with parent ${ref5} as it has parameters`, + `Error at outsideNoParams, Error: Cannot route to ${ref3} with parent ${ref5} as it has parameters`, ), ).toBeInTheDocument(); }); diff --git a/packages/core-components/src/components/DismissableBanner/DismissableBanner.tsx b/packages/core-components/src/components/DismissableBanner/DismissableBanner.tsx index be8e613b61..b2d0c68d17 100644 --- a/packages/core-components/src/components/DismissableBanner/DismissableBanner.tsx +++ b/packages/core-components/src/components/DismissableBanner/DismissableBanner.tsx @@ -56,6 +56,7 @@ const useStyles = makeStyles( content: { width: '100%', maxWidth: 'inherit', + flexWrap: 'nowrap', }, message: { display: 'flex', diff --git a/packages/core-components/src/components/OAuthRequestDialog/LoginRequestListItem.tsx b/packages/core-components/src/components/OAuthRequestDialog/LoginRequestListItem.tsx index b911a9a1d9..ef0d2373e4 100644 --- a/packages/core-components/src/components/OAuthRequestDialog/LoginRequestListItem.tsx +++ b/packages/core-components/src/components/OAuthRequestDialog/LoginRequestListItem.tsx @@ -21,6 +21,7 @@ import ListItemText from '@material-ui/core/ListItemText'; import Typography from '@material-ui/core/Typography'; import Button from '@material-ui/core/Button'; import React, { useState } from 'react'; +import { isError } from '@backstage/errors'; import { PendingAuthRequest } from '@backstage/core-plugin-api'; export type LoginRequestListItemClassKey = 'root'; @@ -42,14 +43,14 @@ type RowProps = { const LoginRequestListItem = ({ request, busy, setBusy }: RowProps) => { const classes = useItemStyles(); - const [error, setError] = useState(); + const [error, setError] = useState(); const handleContinue = async () => { setBusy(true); try { await request.trigger(); } catch (e) { - setError(e); + setError(isError(e) ? e.message : 'An unspecified error occurred'); } finally { setBusy(false); } @@ -64,13 +65,7 @@ const LoginRequestListItem = ({ request, busy, setBusy }: RowProps) => { - {error.message || 'An unspecified error occurred'} - - ) - } + secondary={error && {error}} />