[HTTP/OAS] `zod` support #186190

jloleysens · 2024-06-13T14:30:08Z

Summary

Enable Core's router to directly accept @kbn/zod runtime validation schemas for validation and generate OpenAPI specification (OAS) from them.

Rationale

We have enabled a code first approach to OAS based on runtime validation (see epic) and would like to ensure that this platform capability is available to the maximum number of Kibana developers. Kibana developers use runtime validation libs other than @kbn/config-schema for a variety of reasons. Generally they fall under these themes:

Performance: there have been cases were Joi was not performant enough for validating certain schemas
Team preferences: some teams prefer the language, API or feature set offered by another runtime validation library (see for ex. use of io-ts's is function). Even if, arguably, there are no strong technical reasons for this approach teams have built certain practices and expectations around them.
Validation on the front end: notably validating large JSON blobs of user content. @kbn/config-schema is not suitable for this due to it's raw size (not a problem server side of course).

zod stands out among runtime validation libraries in Kibana (big 3 are @kbn/config-schema, zod and io-ts). zod offers a pragmatic API and the ability to derive JSONSchema for generating OAS. zod is fairly widely adopted in the broader JS ecosystem and gets regular fixes and updates. For these reasons zod is a good fit for Kibana's API needs and likely the library we'd choose today in some parallel universe.

Contributions welcome

This PR was productionized and driven forward largely by @maryam-saeidi 's efforts and investigation into o11y team's adoption of @kbn/config-schema and a subsequent investigation (based on this PR) into zod. If teams have specific needs from either @kbn/config-schema or zod please consider making an upstream contribution before picking yet another runtime validation lib!!

What about `@kbn/config-schema`?

The general advice for (new) developers is to continue using @kbn/config-schema.

Core's position is that we will continue to recommend @kbn/config-schema as the primary, first-class-citizen runtime validation library for all our purposes (SO schema, configuration, API schema) and consider it in long-term maintenance mode. At the same time, we recognise that zod is viable alternative for HTTP APIs that can help increase (o11y) team's investment in Kibana platform-provided capabilities like OAS generation from code.

Usage

Here is an example of using Zod in SLO delete API.

Risks

No present risks of breaking any behaviour as no API is passing @kbn/zod to Kibana router declarations
Another 3rd party library:
- Longer term, lower risk possibility of the library becoming unmaintained. Mitigation: given the growing number of projects depend on zod this seems unlikely and it is always possible for us to contribute to zod directly. The trade-off with value unlocked for Kibana developers seems worth it in this case. Additionally, we wrap zod as @kbn/zod which enables us to shim/fix/improve a large number of aspects of zod like any missing OAS features.
- Removes Kibana Core as the bottleneck for teams if they are looking for specific, modern features zod supports or will support in future (e.g. transform API).

Notes

Replacing joi with zod is a nice goal, but has proven practically infeasible due to their differences in API and behaviour: unfortunately @kbn/config-schema is a leaky wrapper around joi.

Follow up work

[OAS] Add an eslint rule to only import Zod from @kbn/zod #187638

packages/kbn-router-to-openapispec/src/generate_oas.test.ts

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

packages/kbn-router-to-openapispec/src/oas_converter/zod/lib.test.ts

jloleysens

I added a couple of commits (mostly deleting code), otherwise this is looking in pretty good shape!

We'll have to get someone else from Core to do a final final review. But let's make sure CI is happy first :)

packages/kbn-router-to-openapispec/src/__snapshots__/generate_oas.test.ts.snap

packages/kbn-router-to-openapispec/src/generate_oas.test.shared.fixture.ts

packages/kbn-router-to-openapispec/src/generate_oas.test.ts

packages/kbn-router-to-openapispec/src/__snapshots__/generate_oas.test.ts.snap

packages/kbn-router-to-openapispec/src/oas_converter/zod/lib.test.ts

jloleysens · 2024-06-28T16:00:12Z

/ci

maryam-saeidi · 2024-07-02T08:21:02Z

/ci

jloleysens · 2024-07-02T13:08:08Z

/ci

kibana-ci · 2024-07-02T14:38:29Z

💛 Build succeeded, but was flaky

Buildkite Build
Commit: 3f52cb4

Failed CI Steps

FTR Configs #64

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/core-http-server`	193	195	+2

Unknown metric groups

API count

id	before	after	diff
`@kbn/core-http-server`	495	497	+2

ESLint disabled line counts

id	before	after	diff
`@kbn/router-to-openapispec`	1	2	+1

Total ESLint disabled count

id	before	after	diff
`@kbn/router-to-openapispec`	1	2	+1

History

💔 Build #219006 failed 72ac550
💔 Build #218521 failed d2ccdb1

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

pgayvallet

Approach looks good to me, no major concerns in the PR's current state

maryam-saeidi

After this PR is merged, I will update our observability API guidelines to use Zod 🎉

pgayvallet

LGTM

gsoldevila · 2024-07-19T08:53:01Z

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

-
-import { schema } from '@kbn/config-schema';
+import type { ZodType } from '@kbn/zod';
+import { schema, Type } from '@kbn/config-schema';


NIT Type can be imported as a type

gsoldevila · 2024-07-19T09:24:53Z

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

@@ -119,6 +120,8 @@ export class RouteValidator<P = {}, Q = {}, B = {}> {
  ): T {
    if (isConfigSchema(validationRule)) {
      return validationRule.validate(data, {}, namespace);
+    } else if (isZod(validationRule)) {
+      return validationRule.parse(data);


Namespace is not passed here?

Yeah, this is part of why Zod is not a drop-in replacement for Joi, no passing context down via the parse method.

gsoldevila · 2024-07-19T09:31:55Z

packages/kbn-router-to-openapispec/src/oas_converter/zod/lib.ts

+import type { OpenAPIV3 } from 'openapi-types';
+// eslint-disable-next-line import/no-extraneous-dependencies
+import zodToJsonSchema from 'zod-to-json-schema';
+import { KnownParameters } from '../../type';


NIT can be imported as a type

gsoldevila · 2024-07-19T09:33:01Z

packages/kbn-router-to-openapispec/src/oas_converter/zod/lib.ts

+  return new Error(`[Zod converter] ${message}`);
+};
+
+function assertInstanceOfZodType(schema: unknown): asserts schema is z.ZodTypeAny {


asserts? TIL ❤️

gsoldevila · 2024-07-19T09:36:19Z

packages/kbn-router-to-openapispec/src/oas_converter/zod/lib.ts

+  if (instanceofZodTypeKind(type, z.ZodFirstPartyTypeKind.ZodLazy)) {
+    return unwrapZodType(type._def.getter(), unwrapPreprocess);
+  }
+  if (instanceofZodTypeKind(type, z.ZodFirstPartyTypeKind.ZodEffects)) {


Same processing for the 3 scenarios? Seems odd.
Are there any other options that don't require unwrapZodType?
Perhaps it'd be interesting to highlight / illustrate them somehow.

gsoldevila · 2024-07-19T09:42:45Z

packages/kbn-router-to-openapispec/src/oas_converter/zod/lib.ts

+      if (zodSupportsCoerce) {
+        if (!instanceofZodTypeCoercible(subShape)) {
+          throw createError(
+            `Input parser key: "${shapeKey}" must be ZodString, ZodNumber, ZodBoolean, ZodBigInt or ZodDate`


Neither in instanceofZodTypeCoercible nor ZodTypeCoercible (above) you don't have a condition for ZodString. Is that normal?

gsoldevila · 2024-07-19T09:45:02Z

There's quite a lot of logic for zod's OAS converter.
Isn't there any existing library that performs this adaptation?
Haven't checked in detail, but perhaps worth exploring.

jloleysens · 2024-07-19T09:54:08Z

Isn't there any existing library that performs this adaptation?

Good catch @gsoldevila ! Yes there is, this code was copy-pasta'd largely from there. Kinda being treated as a "black box" that we can open if/when we need to.

Because we want to do a few custom things with our OAS, we just cherry-picked the parts that convert the runtime schema to JSONSchema.

gsoldevila

Pre-approving as most of my remarks are related to copy-pasted code

maryam-saeidi · 2024-07-19T13:33:17Z

@gsoldevila Thanks for reviewing this PR!

Regarding the OAS convertor, we will need to revisit it when we use Zod in our products. During my investigation, I noticed we are missing some features, and we need to verify the convertor's result in an actual scenario.

So, I will merge this PR, and we can check your comments in a follow-up PR.

elasticmachine · 2024-07-19T15:54:27Z

💚 Build Succeeded

Buildkite Build
Commit: f1501bc

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/zod`	-	4	+4

Unknown metric groups

API count

id	before	after	diff
`@kbn/zod`	-	1224	+1224

ESLint disabled line counts

id	before	after	diff
`@kbn/router-to-openapispec`	1	2	+1

Total ESLint disabled count

id	before	after	diff
`@kbn/router-to-openapispec`	1	2	+1

Unreferenced deprecated APIs

id	before	after	diff
`@kbn/zod`	-	4	+4

History

💛 Build #222270 was flaky fc8e847
💔 Build #222034 failed 4a2301e
💛 Build #221389 was flaky df883f8
💛 Build #221097 was flaky dc37dea
💚 Build #220032 succeeded 598735f
💔 Build #219814 failed 33b95f5

cc @jloleysens @maryam-saeidi

jloleysens and others added 6 commits June 13, 2024 14:15

add support for zod in oas converter (pass #1)

51bd6b0

allow zod for response validation

2591207

use zod validation

82aee47

[do not keep]

751ef07

Fix type

ee3cd73

Merge branch 'main' into oas/zod-poc

8c45b04

This was referenced Jun 25, 2024

[OAS] Add support for kbn-xsrf #186876

Closed

[OAS] Add support for spaceId #186878

Open

maryam-saeidi added 2 commits June 26, 2024 15:18

Merge branch 'main' into oas/zod-poc

00862c3

Add test for zod OAS generation

bff4536

maryam-saeidi reviewed Jun 28, 2024

View reviewed changes

packages/kbn-router-to-openapispec/src/generate_oas.test.ts Outdated Show resolved Hide resolved

maryam-saeidi reviewed Jun 28, 2024

View reviewed changes

packages/kbn-router-to-openapispec/src/generate_oas.test.util.ts Outdated Show resolved Hide resolved

maryam-saeidi added 2 commits June 28, 2024 15:39

Add unit test for zod oas_conventor

f47b965

Revert changes to status API

61ad417

maryam-saeidi reviewed Jun 28, 2024

View reviewed changes

packages/kbn-router-to-openapispec/src/oas_converter/zod/lib.test.ts Show resolved Hide resolved

maryam-saeidi reviewed Jun 28, 2024

View reviewed changes

packages/kbn-router-to-openapispec/src/oas_converter/zod/lib.test.ts Outdated Show resolved Hide resolved

maryam-saeidi and others added 3 commits June 28, 2024 15:44

Merge branch 'main' into oas/zod-poc

7b79fe3

unified utils a bit

3ea82d7

remove unused funcs

75ee9f9

jloleysens commented Jun 28, 2024

View reviewed changes

fix types and better colocation

d2ccdb1

maryam-saeidi added 2 commits July 2, 2024 10:15

Fix issue with scripts/yarn_deduplicate script

b18b68d

Rename generate_oas.test.shared.fixture filename

72ac550

maryam-saeidi and others added 2 commits July 2, 2024 11:50

Remove recursive test

165f57c

reintroduce ObjectType

3f52cb4

miltonhultgren mentioned this pull request Jul 3, 2024

[WIP] Add typed client helpers to Core HTTP #187479

Closed

jloleysens marked this pull request as draft July 11, 2024 12:20

pgayvallet reviewed Jul 11, 2024

View reviewed changes

jloleysens marked this pull request as ready for review July 12, 2024 08:16

jloleysens added 2 commits July 12, 2024 13:46

Merge branch 'main' into oas/zod-poc

dc37dea

Merge branch 'main' into oas/zod-poc

df883f8

maryam-saeidi approved these changes Jul 16, 2024

View reviewed changes

jloleysens changed the title ~~[OAS] zod support~~ [HTTP/OAS] zod support Jul 17, 2024

jloleysens added the Feature:http label Jul 17, 2024

jloleysens added 2 commits July 17, 2024 13:33

Merge branch 'main' into oas/zod-poc

4a2301e

Merge branch 'main' into oas/zod-poc

fc8e847

pgayvallet approved these changes Jul 19, 2024

View reviewed changes

gsoldevila reviewed Jul 19, 2024

View reviewed changes

gsoldevila approved these changes Jul 19, 2024

View reviewed changes

maryam-saeidi enabled auto-merge (squash) July 19, 2024 14:25

maryam-saeidi disabled auto-merge July 19, 2024 14:25

Merge branch 'main' into oas/zod-poc

f1501bc

jloleysens enabled auto-merge (squash) July 19, 2024 15:17

jloleysens merged commit 6a7a400 into main Jul 19, 2024
36 checks passed

jloleysens deleted the oas/zod-poc branch July 19, 2024 15:53

kibanamachine added v8.16.0 backport:skip This commit does not require backporting labels Jul 19, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[HTTP/OAS] `zod` support #186190

[HTTP/OAS] `zod` support #186190

jloleysens commented Jun 13, 2024 •

edited

Loading

jloleysens left a comment •

edited

Loading

jloleysens commented Jun 28, 2024

maryam-saeidi commented Jul 2, 2024

jloleysens commented Jul 2, 2024

kibana-ci commented Jul 2, 2024

API count

ESLint disabled line counts

Total ESLint disabled count

pgayvallet left a comment

maryam-saeidi left a comment

pgayvallet left a comment

gsoldevila Jul 19, 2024

gsoldevila Jul 19, 2024

jloleysens Jul 19, 2024

gsoldevila Jul 19, 2024

gsoldevila Jul 19, 2024

gsoldevila Jul 19, 2024

gsoldevila Jul 19, 2024 •

edited

Loading

gsoldevila commented Jul 19, 2024 •

edited

Loading

jloleysens commented Jul 19, 2024 •

edited

Loading

gsoldevila left a comment

maryam-saeidi commented Jul 19, 2024

elasticmachine commented Jul 19, 2024

API count

ESLint disabled line counts

Total ESLint disabled count

Unreferenced deprecated APIs

[HTTP/OAS] zod support #186190

[HTTP/OAS] zod support #186190

Conversation

jloleysens commented Jun 13, 2024 • edited Loading

Summary

Rationale

Contributions welcome

What about @kbn/config-schema?

Usage

Risks

Notes

Follow up work

jloleysens left a comment • edited Loading

Choose a reason for hiding this comment

jloleysens commented Jun 28, 2024

maryam-saeidi commented Jul 2, 2024

jloleysens commented Jul 2, 2024

kibana-ci commented Jul 2, 2024

💛 Build succeeded, but was flaky

Failed CI Steps

Metrics [docs]

Public APIs missing comments

API count

ESLint disabled line counts

Total ESLint disabled count

History

pgayvallet left a comment

Choose a reason for hiding this comment

maryam-saeidi left a comment

Choose a reason for hiding this comment

pgayvallet left a comment

Choose a reason for hiding this comment

gsoldevila Jul 19, 2024

Choose a reason for hiding this comment

gsoldevila Jul 19, 2024

Choose a reason for hiding this comment

jloleysens Jul 19, 2024

Choose a reason for hiding this comment

gsoldevila Jul 19, 2024

Choose a reason for hiding this comment

gsoldevila Jul 19, 2024

Choose a reason for hiding this comment

gsoldevila Jul 19, 2024

Choose a reason for hiding this comment

gsoldevila Jul 19, 2024 • edited Loading

Choose a reason for hiding this comment

gsoldevila commented Jul 19, 2024 • edited Loading

jloleysens commented Jul 19, 2024 • edited Loading

gsoldevila left a comment

Choose a reason for hiding this comment

maryam-saeidi commented Jul 19, 2024

elasticmachine commented Jul 19, 2024

💚 Build Succeeded

Metrics [docs]

Public APIs missing comments

API count

ESLint disabled line counts

Total ESLint disabled count

Unreferenced deprecated APIs

History

[HTTP/OAS] `zod` support #186190

[HTTP/OAS] `zod` support #186190

jloleysens commented Jun 13, 2024 •

edited

Loading

What about `@kbn/config-schema`?

jloleysens left a comment •

edited

Loading

gsoldevila Jul 19, 2024 •

edited

Loading

gsoldevila commented Jul 19, 2024 •

edited

Loading

jloleysens commented Jul 19, 2024 •

edited

Loading