-
Notifications
You must be signed in to change notification settings - Fork 8.3k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[HTTP/OAS] Added response schemas for /api/status
#181277
[HTTP/OAS] Added response schemas for /api/status
#181277
Conversation
/ci |
/ci |
Pinging @elastic/kibana-core (Team:Core) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
See comment
packages/core/status/core-status-server-internal/src/routes/status.ts
Outdated
Show resolved
Hide resolved
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Approving as it's technically LGTM
/api/status
/api/status
## Summary Based on the introduction of new response schemas for OAS generation we are going to start the long tail of introducing missing response (`joi`) schemas. We have roughly 520 known public APIs, most of which do not have response schemas defined. We expected a fairly large increase in `@kbn/config-schema` definitions in the coming weeks/months. Regardless of actual outcome and given how slow schema instantiation is, this presents a slight concern for startup time. ## Proposed changes Give consumers guidance and a way to pass in validation lazily. Under the hood we make sure that the lazy schemas only get called once. ```ts /** * A validation schema factory. * * @note Used to lazily create schemas that are otherwise not needed * @note Assume this function will only be called once * * @return A @kbn/config-schema schema * @public */ export type LazyValidator = () => Type<unknown>; /** @public */ export interface VersionedRouteCustomResponseBodyValidation { /** A custom validation function */ custom: RouteValidationFunction<unknown>; } /** @public */ export type VersionedResponseBodyValidation = | LazyValidator | VersionedRouteCustomResponseBodyValidation; /** * Map of response status codes to response schemas * * @note Instantiating response schemas is expensive, especially when it is * not needed in most cases. See example below to ensure this is lazily * provided. * * @note The {@link TypeOf} type utility from @kbn/config-schema can extract * types from lazily created schemas * * @example * ```ts * // Avoid this: * const badResponseSchema = schema.object({ foo: foo.string() }); * // Do this: * const goodResponseSchema = () => schema.object({ foo: foo.string() }); * * type ResponseType = TypeOf<typeof goodResponseSchema>; * ... * .addVersion( * { ... validation: { response: { 200: { body: goodResponseSchema } } } }, * handlerFn * ) * ... * ``` * @public */ export interface VersionedRouteResponseValidation { [statusCode: number]: { body: VersionedResponseBodyValidation; }; unsafe?: { body?: boolean }; } ``` ## Notes * Expected (worst case) in low resource environments is an additional 1.5 seconds to start up time and additional ~70MB to memory pressure which is not a great trade-off for functionality that is only used when OAS generation is on. Related #181277
## Summary Based on the introduction of new response schemas for OAS generation we are going to start the long tail of introducing missing response (`joi`) schemas. We have roughly 520 known public APIs, most of which do not have response schemas defined. We expected a fairly large increase in `@kbn/config-schema` definitions in the coming weeks/months. Regardless of actual outcome and given how slow schema instantiation is, this presents a slight concern for startup time. ## Proposed changes Give consumers guidance and a way to pass in validation lazily. Under the hood we make sure that the lazy schemas only get called once. ```ts /** * A validation schema factory. * * @note Used to lazily create schemas that are otherwise not needed * @note Assume this function will only be called once * * @return A @kbn/config-schema schema * @public */ export type LazyValidator = () => Type<unknown>; /** @public */ export interface VersionedRouteCustomResponseBodyValidation { /** A custom validation function */ custom: RouteValidationFunction<unknown>; } /** @public */ export type VersionedResponseBodyValidation = | LazyValidator | VersionedRouteCustomResponseBodyValidation; /** * Map of response status codes to response schemas * * @note Instantiating response schemas is expensive, especially when it is * not needed in most cases. See example below to ensure this is lazily * provided. * * @note The {@link TypeOf} type utility from @kbn/config-schema can extract * types from lazily created schemas * * @example * ```ts * // Avoid this: * const badResponseSchema = schema.object({ foo: foo.string() }); * // Do this: * const goodResponseSchema = () => schema.object({ foo: foo.string() }); * * type ResponseType = TypeOf<typeof goodResponseSchema>; * ... * .addVersion( * { ... validation: { response: { 200: { body: goodResponseSchema } } } }, * handlerFn * ) * ... * ``` * @public */ export interface VersionedRouteResponseValidation { [statusCode: number]: { body: VersionedResponseBodyValidation; }; unsafe?: { body?: boolean }; } ``` ## Notes * Expected (worst case) in low resource environments is an additional 1.5 seconds to start up time and additional ~70MB to memory pressure which is not a great trade-off for functionality that is only used when OAS generation is on. Related elastic#181277 (cherry picked from commit 97e1d9f)
# Backport This will backport the following commits from `main` to `8.14`: - [[HTTP/OAS] Lazy response schemas (#181622)](#181622) <!--- Backport version: 9.4.3 --> ### Questions ? Please refer to the [Backport tool documentation](https://github.com/sqren/backport) <!--BACKPORT [{"author":{"name":"Jean-Louis Leysens","email":"[email protected]"},"sourceCommit":{"committedDate":"2024-04-29T09:22:44Z","message":"[HTTP/OAS] Lazy response schemas (#181622)\n\n## Summary\r\n\r\nBased on the introduction of new response schemas for OAS generation we\r\nare going to start the long tail of introducing missing response (`joi`)\r\nschemas. We have roughly 520 known public APIs, most of which do not\r\nhave response schemas defined. We expected a fairly large increase in\r\n`@kbn/config-schema` definitions in the coming weeks/months. Regardless\r\nof actual outcome and given how slow schema instantiation is, this\r\npresents a slight concern for startup time.\r\n\r\n## Proposed changes\r\n\r\nGive consumers guidance and a way to pass in validation lazily. Under\r\nthe hood we make sure that the lazy schemas only get called once.\r\n\r\n```ts\r\n\r\n/**\r\n * A validation schema factory.\r\n *\r\n * @note Used to lazily create schemas that are otherwise not needed\r\n * @note Assume this function will only be called once\r\n *\r\n * @return A @kbn/config-schema schema\r\n * @public\r\n */\r\nexport type LazyValidator = () => Type<unknown>;\r\n\r\n/** @public */\r\nexport interface VersionedRouteCustomResponseBodyValidation {\r\n /** A custom validation function */\r\n custom: RouteValidationFunction<unknown>;\r\n}\r\n\r\n/** @public */\r\nexport type VersionedResponseBodyValidation =\r\n | LazyValidator\r\n | VersionedRouteCustomResponseBodyValidation;\r\n\r\n/**\r\n * Map of response status codes to response schemas\r\n *\r\n * @note Instantiating response schemas is expensive, especially when it is\r\n * not needed in most cases. See example below to ensure this is lazily\r\n * provided.\r\n *\r\n * @note The {@link TypeOf} type utility from @kbn/config-schema can extract\r\n * types from lazily created schemas\r\n *\r\n * @example\r\n * ```ts\r\n * // Avoid this:\r\n * const badResponseSchema = schema.object({ foo: foo.string() });\r\n * // Do this:\r\n * const goodResponseSchema = () => schema.object({ foo: foo.string() });\r\n *\r\n * type ResponseType = TypeOf<typeof goodResponseSchema>;\r\n * ...\r\n * .addVersion(\r\n * { ... validation: { response: { 200: { body: goodResponseSchema } } } },\r\n * handlerFn\r\n * )\r\n * ...\r\n * ```\r\n * @public\r\n */\r\nexport interface VersionedRouteResponseValidation {\r\n [statusCode: number]: {\r\n body: VersionedResponseBodyValidation;\r\n };\r\n unsafe?: { body?: boolean };\r\n}\r\n```\r\n\r\n## Notes\r\n\r\n* Expected (worst case) in low resource environments is an additional\r\n1.5 seconds to start up time and additional ~70MB to memory pressure\r\nwhich is not a great trade-off for functionality that is only used when\r\nOAS generation is on.\r\n\r\nRelated https://github.com/elastic/kibana/pull/181277","sha":"97e1d9f4b8b816d45b31a9caa0feca9bbb9c3bd8","branchLabelMapping":{"^v8.15.0$":"main","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["Feature:http","Team:Core","release_note:skip","ci:project-deploy-observability","v8.14.0","v8.15.0"],"title":"[HTTP/OAS] Lazy response schemas","number":181622,"url":"https://github.com/elastic/kibana/pull/181622","mergeCommit":{"message":"[HTTP/OAS] Lazy response schemas (#181622)\n\n## Summary\r\n\r\nBased on the introduction of new response schemas for OAS generation we\r\nare going to start the long tail of introducing missing response (`joi`)\r\nschemas. We have roughly 520 known public APIs, most of which do not\r\nhave response schemas defined. We expected a fairly large increase in\r\n`@kbn/config-schema` definitions in the coming weeks/months. Regardless\r\nof actual outcome and given how slow schema instantiation is, this\r\npresents a slight concern for startup time.\r\n\r\n## Proposed changes\r\n\r\nGive consumers guidance and a way to pass in validation lazily. Under\r\nthe hood we make sure that the lazy schemas only get called once.\r\n\r\n```ts\r\n\r\n/**\r\n * A validation schema factory.\r\n *\r\n * @note Used to lazily create schemas that are otherwise not needed\r\n * @note Assume this function will only be called once\r\n *\r\n * @return A @kbn/config-schema schema\r\n * @public\r\n */\r\nexport type LazyValidator = () => Type<unknown>;\r\n\r\n/** @public */\r\nexport interface VersionedRouteCustomResponseBodyValidation {\r\n /** A custom validation function */\r\n custom: RouteValidationFunction<unknown>;\r\n}\r\n\r\n/** @public */\r\nexport type VersionedResponseBodyValidation =\r\n | LazyValidator\r\n | VersionedRouteCustomResponseBodyValidation;\r\n\r\n/**\r\n * Map of response status codes to response schemas\r\n *\r\n * @note Instantiating response schemas is expensive, especially when it is\r\n * not needed in most cases. See example below to ensure this is lazily\r\n * provided.\r\n *\r\n * @note The {@link TypeOf} type utility from @kbn/config-schema can extract\r\n * types from lazily created schemas\r\n *\r\n * @example\r\n * ```ts\r\n * // Avoid this:\r\n * const badResponseSchema = schema.object({ foo: foo.string() });\r\n * // Do this:\r\n * const goodResponseSchema = () => schema.object({ foo: foo.string() });\r\n *\r\n * type ResponseType = TypeOf<typeof goodResponseSchema>;\r\n * ...\r\n * .addVersion(\r\n * { ... validation: { response: { 200: { body: goodResponseSchema } } } },\r\n * handlerFn\r\n * )\r\n * ...\r\n * ```\r\n * @public\r\n */\r\nexport interface VersionedRouteResponseValidation {\r\n [statusCode: number]: {\r\n body: VersionedResponseBodyValidation;\r\n };\r\n unsafe?: { body?: boolean };\r\n}\r\n```\r\n\r\n## Notes\r\n\r\n* Expected (worst case) in low resource environments is an additional\r\n1.5 seconds to start up time and additional ~70MB to memory pressure\r\nwhich is not a great trade-off for functionality that is only used when\r\nOAS generation is on.\r\n\r\nRelated https://github.com/elastic/kibana/pull/181277","sha":"97e1d9f4b8b816d45b31a9caa0feca9bbb9c3bd8"}},"sourceBranch":"main","suggestedTargetBranches":["8.14"],"targetPullRequestStates":[{"branch":"8.14","label":"v8.14.0","branchLabelMappingKey":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"main","label":"v8.15.0","branchLabelMappingKey":"^v8.15.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/181622","number":181622,"mergeCommit":{"message":"[HTTP/OAS] Lazy response schemas (#181622)\n\n## Summary\r\n\r\nBased on the introduction of new response schemas for OAS generation we\r\nare going to start the long tail of introducing missing response (`joi`)\r\nschemas. We have roughly 520 known public APIs, most of which do not\r\nhave response schemas defined. We expected a fairly large increase in\r\n`@kbn/config-schema` definitions in the coming weeks/months. Regardless\r\nof actual outcome and given how slow schema instantiation is, this\r\npresents a slight concern for startup time.\r\n\r\n## Proposed changes\r\n\r\nGive consumers guidance and a way to pass in validation lazily. Under\r\nthe hood we make sure that the lazy schemas only get called once.\r\n\r\n```ts\r\n\r\n/**\r\n * A validation schema factory.\r\n *\r\n * @note Used to lazily create schemas that are otherwise not needed\r\n * @note Assume this function will only be called once\r\n *\r\n * @return A @kbn/config-schema schema\r\n * @public\r\n */\r\nexport type LazyValidator = () => Type<unknown>;\r\n\r\n/** @public */\r\nexport interface VersionedRouteCustomResponseBodyValidation {\r\n /** A custom validation function */\r\n custom: RouteValidationFunction<unknown>;\r\n}\r\n\r\n/** @public */\r\nexport type VersionedResponseBodyValidation =\r\n | LazyValidator\r\n | VersionedRouteCustomResponseBodyValidation;\r\n\r\n/**\r\n * Map of response status codes to response schemas\r\n *\r\n * @note Instantiating response schemas is expensive, especially when it is\r\n * not needed in most cases. See example below to ensure this is lazily\r\n * provided.\r\n *\r\n * @note The {@link TypeOf} type utility from @kbn/config-schema can extract\r\n * types from lazily created schemas\r\n *\r\n * @example\r\n * ```ts\r\n * // Avoid this:\r\n * const badResponseSchema = schema.object({ foo: foo.string() });\r\n * // Do this:\r\n * const goodResponseSchema = () => schema.object({ foo: foo.string() });\r\n *\r\n * type ResponseType = TypeOf<typeof goodResponseSchema>;\r\n * ...\r\n * .addVersion(\r\n * { ... validation: { response: { 200: { body: goodResponseSchema } } } },\r\n * handlerFn\r\n * )\r\n * ...\r\n * ```\r\n * @public\r\n */\r\nexport interface VersionedRouteResponseValidation {\r\n [statusCode: number]: {\r\n body: VersionedResponseBodyValidation;\r\n };\r\n unsafe?: { body?: boolean };\r\n}\r\n```\r\n\r\n## Notes\r\n\r\n* Expected (worst case) in low resource environments is an additional\r\n1.5 seconds to start up time and additional ~70MB to memory pressure\r\nwhich is not a great trade-off for functionality that is only used when\r\nOAS generation is on.\r\n\r\nRelated https://github.com/elastic/kibana/pull/181277","sha":"97e1d9f4b8b816d45b31a9caa0feca9bbb9c3bd8"}}]}] BACKPORT--> Co-authored-by: Jean-Louis Leysens <[email protected]>
💔 All backports failed
Manual backportTo create the backport manually run:
Questions ?Please refer to the Backport tool documentation |
Friendly reminder: Looks like this PR hasn’t been backported yet. |
Friendly reminder: Looks like this PR hasn’t been backported yet. |
Summary
Part #180056. Adds new response schemas to the
/api/status
endpoint for the purposes of OAS generation.How to test
server.oas.enabled: true
tokibana.dev.yml
yarn start --no-base-path
curl -s -uelastic:changeme http://localhost:5601/api/oas\?pathStartsWith\=/api/status | jq
output
Related to #181622
Notes