[HTTP/OAS] Ability to exclude routes from introspection #192675

jloleysens · 2024-09-12T10:25:50Z

Summary

Certain routes, like "system" routes should be excludable from introspection. Among these are also "HTTP resource" routes that are intended to server rendered HTML, CSS or JS.

To this end a new registration option was added: excludeFromOAS: boolean that will exclude routes from OAS documents created by Kibana.

jloleysens · 2024-09-12T11:49:45Z

/ci

kibana-ci · 2024-09-12T13:27:49Z

💛 Build succeeded, but was flaky

Buildkite Build
Commit: e70e06a

Failed CI Steps

FTR Configs #97

Test Failures

[job] [logs] FTR Configs #97 / data plugin Session management Dashboard starts a session on filter change

Metrics [docs]

Public APIs missing comments

Total count of every public API that lacks a comment. Target amount is 0. Run node scripts/build_api_docs --plugin [yourplugin] --stats comments for more detailed information.

id	before	after	diff
`@kbn/router-to-openapispec`	5	10	+5

Unknown metric groups

API count

id	before	after	diff
`@kbn/core-http-server`	495	496	+1
`@kbn/router-to-openapispec`	5	10	+5
total			+6

To update your PR or re-run it, just comment with:
@elasticmachine merge upstream

jloleysens · 2024-10-09T09:25:25Z

/ci

jloleysens · 2024-10-09T10:40:00Z

packages/core/http/core-http-server-internal/src/http_service.ts

+        let filters: GenerateOpenApiDocumentOptionsFilters;
+        let query: TypeOf<typeof querySchema>;
+        try {
+          query = querySchema.validate(req.query);


Refactor to using config-schema, just cleanup

packages/core/http/core-http-router-server-internal/src/router.ts

elasticmachine · 2024-10-09T11:01:42Z

Pinging @elastic/kibana-core (Team:Core)

jloleysens · 2024-10-09T13:38:41Z

packages/kbn-router-to-openapispec/src/util.ts

 >(
  routes: R[],
  filters: GenerateOpenApiDocumentOptionsFilters = {}
 ): R[] => {
  if (Object.getOwnPropertyNames(filters).length === 0) return routes;
  return routes.filter((route) => {
+    if (route.options.excludeFromOAS) return false;


Where we actually exclude routes from OAS docs.

Bamieh

Added a nit you can ignore or address as you see fit. otherwise LGTM

Bamieh · 2024-10-09T14:09:24Z

packages/core/http/core-http-router-server-internal/src/router.ts

@@ -237,7 +238,7 @@ export class Router<Context extends RequestHandlerContextBase = RequestHandlerCo
    if (excludeVersionedRoutes) {
      return this.routes.filter((route) => !route.isVersioned);
    }
-    return [...this.routes];
+    return this.routes;


probably unnecessary but this might remove a potential mutation guard we accedentaly had

Ah man, I somehow missed this. That's a good point, will fix.

elasticmachine · 2024-10-09T15:34:20Z

💛 Build succeeded, but was flaky

Buildkite Build
Commit: 1bfe9e1

Failed CI Steps

FTR Configs #102

Test Failures

[job] [logs] FTR Configs #102 / Fleet Endpoints Integrations inputs_with_standalone_docker_agent generate a valid config for standalone agents

Metrics [docs]

Public APIs missing comments

Total count of every public API that lacks a comment. Target amount is 0. Run node scripts/build_api_docs --plugin [yourplugin] --stats comments for more detailed information.

id	before	after	diff
`@kbn/router-to-openapispec`	5	10	+5

Unknown metric groups

API count

id	before	after	diff
`@kbn/core-http-server`	530	531	+1
`@kbn/router-to-openapispec`	5	10	+5
total			+6

History

💔 Build #240630 failed de17d30
💔 Build #240582 failed 4fa18e3

kibanamachine · 2024-10-09T16:32:01Z

Starting backport for target branches: 8.x

https://github.com/elastic/kibana/actions/runs/11259199758

(cherry picked from commit 2327681)

kibanamachine · 2024-10-09T17:07:01Z

💚 All backports created successfully

Status	Branch	Result
✅	8.x

Note: Successful backport PRs will be merged automatically after passing CI.

Questions ?

Please refer to the Backport tool documentation

… (#195652) # Backport This will backport the following commits from `main` to `8.x`: - [[HTTP/OAS] Ability to exclude routes from introspection (#192675)](#192675)  ### Questions ? Please refer to the [Backport tool documentation](https://github.com/sqren/backport)  Co-authored-by: Jean-Louis Leysens <[email protected]>

## Summary Small follow up based on #192675 (comment)

## Summary Small follow up based on elastic#192675 (comment) (cherry picked from commit a481da6)

…195714) # Backport This will backport the following commits from `main` to `8.x`: - [[HTTP] Copy array returned by `getRoutes` (#195647)](#195647)  ### Questions ? Please refer to the [Backport tool documentation](https://github.com/sqren/backport)  Co-authored-by: Jean-Louis Leysens <[email protected]>

…#195940) ## Summary Follow up on #195464 Adds public route registrar option `httpResource` to distinguish API routes from routes intended to be used for loading resources, [for ex](https://github.com/elastic/kibana/blob/bd22f1370fc55179ea6f2737176570176f700b6e/x-pack/plugins/security/server/routes/authentication/oidc.ts#L36). This enables us to avoid returning the version header `elastic-api-version` for HTTP resource routes. It's still possible for API authors to use the versioned router for things that should be HTTP resources, but it's assumed that all routes registered through HTTP resources services are: 1. Public 2. Not versioned (focus of this PR) 3. Not documented (done in #192675) ### Checklist - [x] [Unit or functional tests](https://www.elastic.co/guide/en/kibana/master/development-tests.html) were updated or added to match the most common scenarios --------- Co-authored-by: kibanamachine <[email protected]>

…elastic#195940) ## Summary Follow up on elastic#195464 Adds public route registrar option `httpResource` to distinguish API routes from routes intended to be used for loading resources, [for ex](https://github.com/elastic/kibana/blob/bd22f1370fc55179ea6f2737176570176f700b6e/x-pack/plugins/security/server/routes/authentication/oidc.ts#L36). This enables us to avoid returning the version header `elastic-api-version` for HTTP resource routes. It's still possible for API authors to use the versioned router for things that should be HTTP resources, but it's assumed that all routes registered through HTTP resources services are: 1. Public 2. Not versioned (focus of this PR) 3. Not documented (done in elastic#192675) ### Checklist - [x] [Unit or functional tests](https://www.elastic.co/guide/en/kibana/master/development-tests.html) were updated or added to match the most common scenarios --------- Co-authored-by: kibanamachine <[email protected]> (cherry picked from commit 72f3d2d)

…header (#195940) (#196324) # Backport This will backport the following commits from `main` to `8.x`: - [[Http] Make HTTP resource routes respond without the versioned header (#195940)](#195940)  ### Questions ? Please refer to the [Backport tool documentation](https://github.com/sqren/backport)  Co-authored-by: Jean-Louis Leysens <[email protected]>

jloleysens added 3 commits September 12, 2024 12:02

refactor oas route to use config schema

df35cfe

added capability to exclude routes from introspection

8097bd5

added field to types and fixed minor typo

e70e06a

Merge branch 'main' into oas/add-option-to-exclude-route-from-oas-gen

4fa18e3

jloleysens commented Oct 9, 2024

View reviewed changes

jloleysens added 3 commits October 9, 2024 12:48

hiddenFromIntrospection -> excludeFromOAS

50430ec

use the excludeFromOAS option in the oas lib code instead

b964e11

cleanup tests

de17d30

jloleysens marked this pull request as ready for review October 9, 2024 11:01

jloleysens requested a review from a team as a code owner October 9, 2024 11:01

jloleysens added Team:Core Core services & architecture: plugins, logging, config, saved objects, http, ES client, i18n, etc v9.0.0 Feature:OAS Work or issues related to Core-provided mechanisms for generating OAS v8.16.0 backport:version Backport to applied version labels labels Oct 9, 2024

jloleysens added the release_note:skip Skip the PR/issue when compiling release notes label Oct 9, 2024

Merge branch 'main' into oas/add-option-to-exclude-route-from-oas-gen

1bfe9e1

jloleysens commented Oct 9, 2024

View reviewed changes

Bamieh approved these changes Oct 9, 2024

View reviewed changes

jloleysens merged commit 2327681 into elastic:main Oct 9, 2024
23 checks passed

jloleysens mentioned this pull request Oct 9, 2024

[HTTP] Copy array returned by getRoutes #195647

Merged

kibanamachine pushed a commit to kibanamachine/kibana that referenced this pull request Oct 9, 2024

[HTTP/OAS] Ability to exclude routes from introspection (elastic#192675)

d849e63

(cherry picked from commit 2327681)

kibanamachine mentioned this pull request Oct 9, 2024

[8.x] [HTTP/OAS] Ability to exclude routes from introspection (#192675) #195652

Merged

jloleysens added a commit that referenced this pull request Oct 10, 2024

[HTTP] Copy array returned by getRoutes (#195647)

a481da6

## Summary Small follow up based on #192675 (comment)

kibanamachine pushed a commit to kibanamachine/kibana that referenced this pull request Oct 10, 2024

[HTTP] Copy array returned by getRoutes (elastic#195647)

1d70414

## Summary Small follow up based on elastic#192675 (comment) (cherry picked from commit a481da6)

jloleysens mentioned this pull request Oct 11, 2024

[Http] Make HTTP resource routes respond without the versioned header #195940

Merged

1 task

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[HTTP/OAS] Ability to exclude routes from introspection #192675

[HTTP/OAS] Ability to exclude routes from introspection #192675

jloleysens commented Sep 12, 2024 •

edited by kibanamachine

Loading

jloleysens commented Sep 12, 2024

kibana-ci commented Sep 12, 2024

API count

jloleysens commented Oct 9, 2024

jloleysens Oct 9, 2024 •

edited

Loading

elasticmachine commented Oct 9, 2024

jloleysens Oct 9, 2024

Bamieh left a comment

Bamieh Oct 9, 2024

jloleysens Oct 9, 2024

elasticmachine commented Oct 9, 2024

API count

kibanamachine commented Oct 9, 2024

kibanamachine commented Oct 9, 2024

[HTTP/OAS] Ability to exclude routes from introspection #192675

[HTTP/OAS] Ability to exclude routes from introspection #192675

Conversation

jloleysens commented Sep 12, 2024 • edited by kibanamachine Loading

Summary

jloleysens commented Sep 12, 2024

kibana-ci commented Sep 12, 2024

💛 Build succeeded, but was flaky

Failed CI Steps

Test Failures

Metrics [docs]

Public APIs missing comments

API count

jloleysens commented Oct 9, 2024

jloleysens Oct 9, 2024 • edited Loading

Choose a reason for hiding this comment

elasticmachine commented Oct 9, 2024

jloleysens Oct 9, 2024

Choose a reason for hiding this comment

Bamieh left a comment

Choose a reason for hiding this comment

Bamieh Oct 9, 2024

Choose a reason for hiding this comment

jloleysens Oct 9, 2024

Choose a reason for hiding this comment

elasticmachine commented Oct 9, 2024

💛 Build succeeded, but was flaky

Failed CI Steps

Test Failures

Metrics [docs]

Public APIs missing comments

API count

History

kibanamachine commented Oct 9, 2024

kibanamachine commented Oct 9, 2024

💚 All backports created successfully

Questions ?

jloleysens commented Sep 12, 2024 •

edited by kibanamachine

Loading

jloleysens Oct 9, 2024 •

edited

Loading