diff --git a/README.md b/README.md index 72974337..052f6210 100644 --- a/README.md +++ b/README.md @@ -1,43 +1,111 @@ # Cycle API Spec - + + - cycle + cycle + -This repository contains the [OpenAPI](https://www.openapis.org/) definitions for the [Cycle API](https://api-docs.cycle.io). It is used in several downstream API clients and projects, and is the basis of our API documentation. +This repository contains the [OpenAPI](https://www.openapis.org/) definitions for the [Cycle Platform](https://cycle.io). +This spec is used to generate various API clients, used by our team internally, and also the foundation of our API documentation. -⚠️ This spec is still under development. While most endpoints should be stable, there are still edge cases and small discrepancies that are actively being worked on. - -While no major breaking changes are expected, we can't guarantee that any downstream clients won't be affected by changes to schemas (such as marking properties as null or required). When we believe the spec to be stable, we'll release v1.0.0. +⚠️ This spec is still under development. While most endpoints should be stable, there are still edge cases and small discrepancies that are actively being worked on. While no major breaking changes are expected, we can't guarantee that any downstream clients won't be affected by changes to schemas. ## APIs -### Public API +### Platform API + +https://api.cycle.io + +[Documentation](https://api-docs.cycle.io) + +The platform API is the general use API for the Cycle Platform, and is available to all Cycle customers. It is the same API consumed by Cycle's portal, and is the main way to interact with all aspects of the platform. -The public API is the general use API for the Cycle Platform, located at https://api.cycle.io. The endpoints for this API are located under `/public`. +See the [platform](./platform/) folder for implementation. ### Internal API -The internal API is used within containers running on the Cycle Platform, and provide a convenient means to communicate with the platform from within a container to unlock advanced use cases (such as custom monitoring/tooling). +[Documentation](https://internal-api.docs.cycle.io) + +Inside every container running on Cycle, there is a Unix socket mounted at `/var/run/cycle/api/api.sock`. You can send HTTP requests over this socket to access information about the local environment, access secrets, and much more. The way this internal API functions is very similar to how Cycle's main API works, though the purpose is different. The internal API is primarily used by instances to learn about their environment, and dynamically update as deployments change. + +See the [internal](./internal/) folder for implementation. + +### Scheduler API + +[Documentation](https://scheduler-api.docs.cycle.io/) + +The scheduler API is used to interact with the [Scheduler Service](https://cycle.io/docs/platform/scheduler-service) inside of +an environment on Cycle. The scheduler service can be accessed from other containers in the environment over the private network, +or the scheduler service can be [made available over the public internet](https://cycle.io/docs/platform/scheduler-service). + +See the [scheduler](./scheduler/) folder for implementation. + +### Infrastructure Abstraction Layer API + +[Documentation](https://cycle-ial.redoc.ly/) + +Cycle's Infrastructure Abstract Layer (IAL) API. Endpoints listed here should be implemented by the customer, and Cycle will call the various endpoints over the lifecycle of provisioning and decommissioning servers. + +For more information, check out the official [Infrastructure Abstraction Layer Documentation](https://cycle.io/docs/platform/infrastructure-abstraction-layer). + +### Stack Spec + +While not truly an API spec, the stack spec defines the JSON schema for a [Cycle Stack File](https://cycle.io/docs/platform/introduction-to-stacks). The JSON schema is useful for editor validation etc. + +The compiled stack spec schema is committed to this repo and hosted on [JSON Schema Store](https://www.schemastore.org/json/) ## Building the APIs -The APIs are built using the [Redocly CLI](https://redocly.com/redocly-cli/). It stitches together the various files and combines them into a single spec file for easy consumption by other tools. +The APIs can be consumed by tools that support stitching together specs divided between multiple files, or built +into a single file using the [Redocly CLI](https://redocly.com/redocly-cli/). ### Prerequisites You must have `npm` installed on your machine, or run inside a container with `npm` in the PATH. -### Building the Public API +### Building the Platform API -`npm run build:public` +`npm run build:platform` -The outputted file is located at `/dist/public-api.yml` +The outputted file is located at `/dist/platform.yml` ### Building the Internal API `npm run build:internal` -The outputted file is located at `/dist/internal-api.yml` +The outputted file is located at `/dist/internal.yml` + +### Building the Scheduler API + +`npm run build:scheduler` + +The outputted file is located at `/dist/scheduler.yml` + +### Building the Infrastructure Abstraction Layer API + +`npm run build:ial` + +The outputted file is located at `/dist/ial.yml` + +### Building the Stack Spec + +`npm run build:stackspec` + +This will build the stack spec into a single JSON schema file, and save it to ./stackspec/stackspec.json. + +**This file should be committed to the repo.** + +## Downconverting to OpenAPI 3.0.3 + +The API specs in this repo are written using the OpenAPI 3.1.0 standard. Some code generators and other tools haven't yet +been updated to support 3.1.0, which can be an inconvenience. For us, it seems nearly all golang client generators don't +support 3.1.0 (if you find one let us know!). + +To resolve this, we've created a script that will downconvert the openapi spec to 3.0.3. Of course, some fidelity is lost +with these conversions, so it may not be a perfect 1:1 with the 'true' spec, but hopefully is good enough to generate clients +off of when necessary. + +To downconvert, run `npm run downconvert:platform`. The script will output to `dist/platform-3.0.3.yml`. \ No newline at end of file diff --git a/components/schemas/containers/config/ContainerDeploy.yml b/components/schemas/containers/config/ContainerDeploy.yml index 4e1f067b..f06eab7e 100644 --- a/components/schemas/containers/config/ContainerDeploy.yml +++ b/components/schemas/containers/config/ContainerDeploy.yml @@ -90,14 +90,7 @@ properties: - array - "null" items: - type: string - enum: - - SIGTERM - - SIGINT - - SIGUSR1 - - SIGUSR2 - - SIGHUP - - SIGQUIT + $ref: ShutdownSignal.yml description: Process signal sent to the container process. startup: type: object diff --git a/components/schemas/containers/config/ShutdownSignal.yml b/components/schemas/containers/config/ShutdownSignal.yml new file mode 100644 index 00000000..52438fc6 --- /dev/null +++ b/components/schemas/containers/config/ShutdownSignal.yml @@ -0,0 +1,10 @@ +title: ShutdownSignal +type: string +description: Process signals that Cycle can be configured to send to the container on a shutdown event. +enum: + - SIGTERM + - SIGINT + - SIGUSR1 + - SIGUSR2 + - SIGHUP + - SIGQUIT diff --git a/components/schemas/containers/instances/Instance.yml b/components/schemas/containers/instances/Instance.yml index 5da6f7ae..8d7a0c81 100644 --- a/components/schemas/containers/instances/Instance.yml +++ b/components/schemas/containers/instances/Instance.yml @@ -114,4 +114,4 @@ properties: $ref: ../../DateTime.yml deleted: description: The timestamp of when the instance was deleted. - $ref: ../../DateTime.yml + $ref: ../../DateTime.yml \ No newline at end of file diff --git a/components/schemas/dns/records/RecordTypes.yml b/components/schemas/dns/records/RecordTypes.yml index 9e1966ac..61f2a601 100644 --- a/components/schemas/dns/records/RecordTypes.yml +++ b/components/schemas/dns/records/RecordTypes.yml @@ -175,9 +175,7 @@ properties: - type: object properties: deployment: - type: - - object - - "null" + type: object description: Information about the deployment this record points to. required: - environment_id diff --git a/components/schemas/environments/EnvironmentFeatures.yml b/components/schemas/environments/EnvironmentFeatures.yml index 9a435ed1..811a8098 100644 --- a/components/schemas/environments/EnvironmentFeatures.yml +++ b/components/schemas/environments/EnvironmentFeatures.yml @@ -19,6 +19,6 @@ properties: type: string enum: - limited - - standard + - basic - premium - enterprise diff --git a/components/schemas/environments/services/DiscoveryEnvironmentService.yml b/components/schemas/environments/services/DiscoveryEnvironmentService.yml index a6ddad5f..72aec9b3 100644 --- a/components/schemas/environments/services/DiscoveryEnvironmentService.yml +++ b/components/schemas/environments/services/DiscoveryEnvironmentService.yml @@ -5,7 +5,6 @@ required: - enable - container_id - high_availability - - config properties: enable: type: boolean diff --git a/components/schemas/environments/services/LoadBalancerEnvironmentService.yml b/components/schemas/environments/services/LoadBalancerEnvironmentService.yml index 5bc92976..882e240c 100644 --- a/components/schemas/environments/services/LoadBalancerEnvironmentService.yml +++ b/components/schemas/environments/services/LoadBalancerEnvironmentService.yml @@ -5,7 +5,6 @@ required: - enable - container_id - high_availability - - config properties: enable: type: boolean diff --git a/components/schemas/environments/services/SchedulerEnvironmentService.yml b/components/schemas/environments/services/SchedulerEnvironmentService.yml index 183cedea..2dff670d 100644 --- a/components/schemas/environments/services/SchedulerEnvironmentService.yml +++ b/components/schemas/environments/services/SchedulerEnvironmentService.yml @@ -7,7 +7,6 @@ required: - enable - container_id - high_availablity - # - config properties: enable: type: boolean diff --git a/components/schemas/environments/services/VpnEnvironmentService.yml b/components/schemas/environments/services/VpnEnvironmentService.yml index 9d8c8ddf..35f0f87d 100644 --- a/components/schemas/environments/services/VpnEnvironmentService.yml +++ b/components/schemas/environments/services/VpnEnvironmentService.yml @@ -5,7 +5,6 @@ required: - enable - container_id - high_availability - - config properties: enable: type: boolean diff --git a/components/schemas/environments/services/discovery/DiscoveryConfig.yml b/components/schemas/environments/services/discovery/DiscoveryConfig.yml index 24473071..29ebe30e 100644 --- a/components/schemas/environments/services/discovery/DiscoveryConfig.yml +++ b/components/schemas/environments/services/discovery/DiscoveryConfig.yml @@ -35,6 +35,8 @@ properties: type: string custom_resolvers: description: "A list of custom DNS resolver strings. Can specifify domains or ips." - type: array - items: - type: string + oneOf: + - type: array + items: + type: string + - type: "null" diff --git a/components/schemas/environments/services/loadbalancer/config/types/v1/V1LbConfigRouter.yml b/components/schemas/environments/services/loadbalancer/config/types/v1/V1LbConfigRouter.yml index 18c6a41a..18b3c2c0 100644 --- a/components/schemas/environments/services/loadbalancer/config/types/v1/V1LbConfigRouter.yml +++ b/components/schemas/environments/services/loadbalancer/config/types/v1/V1LbConfigRouter.yml @@ -74,7 +74,6 @@ properties: type: integer description: If a destination is unavailable, retry up to [x] times, instead of immediately failing with a 503/504 error. destination_prioritization: - default: null oneOf: - type: string description: > diff --git a/components/schemas/environments/services/loadbalancer/config/types/v1/V1LbType.yml b/components/schemas/environments/services/loadbalancer/config/types/v1/V1LbType.yml index 7df2d6c5..45d2d962 100644 --- a/components/schemas/environments/services/loadbalancer/config/types/v1/V1LbType.yml +++ b/components/schemas/environments/services/loadbalancer/config/types/v1/V1LbType.yml @@ -17,7 +17,9 @@ properties: enum: - "v1" details: - $ref: V1LbConfig.yml + anyOf: + - $ref: V1LbConfig.yml + - type: "null" bind_host: description: | Binds the load balancer to the host server IP address. diff --git a/components/schemas/environments/services/loadbalancer/config/types/v1/WafConfig.yml b/components/schemas/environments/services/loadbalancer/config/types/v1/WafConfig.yml index 0c70a901..f7d3f09a 100644 --- a/components/schemas/environments/services/loadbalancer/config/types/v1/WafConfig.yml +++ b/components/schemas/environments/services/loadbalancer/config/types/v1/WafConfig.yml @@ -33,6 +33,8 @@ properties: enum: - any - all + # legacy value TODO remove + - "" conditions: description: An array of the specific conditions for the rule. type: array diff --git a/components/schemas/environments/services/loadbalancer/config/types/v1/routers/HttpRouterConfig.yml b/components/schemas/environments/services/loadbalancer/config/types/v1/routers/HttpRouterConfig.yml index 9e605b54..2e243c21 100644 --- a/components/schemas/environments/services/loadbalancer/config/types/v1/routers/HttpRouterConfig.yml +++ b/components/schemas/environments/services/loadbalancer/config/types/v1/routers/HttpRouterConfig.yml @@ -75,7 +75,9 @@ properties: description: Replacement value. type: string url: - type: string + type: + - string + - "null" description: | The URL to forward the request to. diff --git a/components/schemas/images/Image.yml b/components/schemas/images/Image.yml index 04d38ca4..47336540 100644 --- a/components/schemas/images/Image.yml +++ b/components/schemas/images/Image.yml @@ -158,7 +158,6 @@ properties: type: string description: A set command to be run if a signal is called. source: - x-ogen-name: ImageSourceDetails type: object discriminator: propertyName: type diff --git a/components/schemas/images/origins/cycleUpload/CycleUploadOrigin.yml b/components/schemas/images/origins/cycleUpload/CycleUploadOrigin.yml index d1dc04f1..bd2baed9 100644 --- a/components/schemas/images/origins/cycleUpload/CycleUploadOrigin.yml +++ b/components/schemas/images/origins/cycleUpload/CycleUploadOrigin.yml @@ -5,6 +5,9 @@ description: | In order to utilize this image origin type, a tar file of an OCI compliant image will need to be generated and pushed directly to the factory. The authentication token is generated when this image is created, and expires at the provided time. Once you have a token, it can be uploaded as multipart form data under the key `file.tar`, directly to the factory at `https://factory.cycle.io:9414/v1/images//upload?hub-id=&token=`. +required: + - type + - details properties: type: type: string diff --git a/components/schemas/images/sources/BucketImageSourceType.yml b/components/schemas/images/sources/BucketImageSourceType.yml index 8b8a6f19..9d6e3928 100644 --- a/components/schemas/images/sources/BucketImageSourceType.yml +++ b/components/schemas/images/sources/BucketImageSourceType.yml @@ -1,8 +1,8 @@ title: BucketImageSource type: object required: - - id - - origin + - type + - details properties: type: type: string diff --git a/components/schemas/images/sources/DirectImageSourceType.yml b/components/schemas/images/sources/DirectImageSourceType.yml index f09110ed..fd0eeda6 100644 --- a/components/schemas/images/sources/DirectImageSourceType.yml +++ b/components/schemas/images/sources/DirectImageSourceType.yml @@ -1,8 +1,8 @@ title: DirectImageSource type: object required: - - id - - origin + - type + - details properties: type: type: string diff --git a/components/schemas/images/sources/StackImageSourceType.yml b/components/schemas/images/sources/StackImageSourceType.yml index affec15a..c2545a28 100644 --- a/components/schemas/images/sources/StackImageSourceType.yml +++ b/components/schemas/images/sources/StackImageSourceType.yml @@ -1,8 +1,8 @@ title: StackImageSource type: object required: - - id - - origin + - type + - details properties: type: type: string diff --git a/components/schemas/infrastructure/servers/Server.yml b/components/schemas/infrastructure/servers/Server.yml index 7aa6c293..a16fd8b1 100644 --- a/components/schemas/infrastructure/servers/Server.yml +++ b/components/schemas/infrastructure/servers/Server.yml @@ -1,5 +1,4 @@ title: Server -x-ogen-name: InfraServer type: object description: The server resource, referring to servers that have been deployed to a Cycle hub. required: diff --git a/components/schemas/monitoring/events/EventType.yml b/components/schemas/monitoring/events/EventType.yml index 881cfd9f..03f8ed78 100644 --- a/components/schemas/monitoring/events/EventType.yml +++ b/components/schemas/monitoring/events/EventType.yml @@ -16,7 +16,6 @@ enum: - container.instance.healthcheck.recovered - container.instance.volume.extend.failed - container.instance.healthcheck.restarted - - container.instance.migration.failed - container.instance.migration.completed - container.instance.migration.failed - container.instance.network.interfaces.create.failed diff --git a/components/schemas/scoped-variables/ScopedVariableAccess.yml b/components/schemas/scoped-variables/ScopedVariableAccess.yml index 230dacce..99e606a9 100644 --- a/components/schemas/scoped-variables/ScopedVariableAccess.yml +++ b/components/schemas/scoped-variables/ScopedVariableAccess.yml @@ -29,10 +29,6 @@ properties: type: - object - "null" - # avoid conflicting name in ogen generator with the Decode method - x-ogen-properties: - decode: - name: "DecodeBase64" required: - decode - path diff --git a/components/schemas/stacks/builds/StackBuild.yml b/components/schemas/stacks/builds/StackBuild.yml index fb818927..521c7d0b 100644 --- a/components/schemas/stacks/builds/StackBuild.yml +++ b/components/schemas/stacks/builds/StackBuild.yml @@ -22,7 +22,6 @@ properties: - $ref: ../../../../stackspec/schema/StackSpec.yml - type: "null" about: - x-ogen-name: StackBuildAboutDetails type: object description: Information about the stack build. required: diff --git a/components/schemas/stacks/builds/StackBuildInstructions.yml b/components/schemas/stacks/builds/StackBuildInstructions.yml index fe1ff6c2..5428b3cd 100644 --- a/components/schemas/stacks/builds/StackBuildInstructions.yml +++ b/components/schemas/stacks/builds/StackBuildInstructions.yml @@ -1,5 +1,4 @@ title: StackBuildInstructions -x-ogen-name: StackBuildInstructionsDetails type: object description: Additional instructions used when generating this stack build. properties: diff --git a/package-lock.json b/package-lock.json index 54023853..ca7b5471 100644 --- a/package-lock.json +++ b/package-lock.json @@ -8,10 +8,15 @@ "name": "@cycleplatform/api-spec", "version": "1.0.0", "license": "Apache-2.0", + "dependencies": { + "@apiture/openapi-down-convert": "github:avandecreme/openapi-down-convert#nullable_pr" + }, "devDependencies": { "@apidevtools/json-schema-ref-parser": "^11.5.4", "@redocly/cli": "1.11.0", - "@types/node": "^20.12.7" + "@types/node": "^20.12.7", + "@types/yamljs": "^0.2.34", + "yamljs": "^0.3.0" } }, "node_modules/@apidevtools/json-schema-ref-parser": { @@ -31,6 +36,19 @@ "url": "https://github.com/sponsors/philsturgeon" } }, + "node_modules/@apiture/openapi-down-convert": { + "version": "0.13.2", + "resolved": "git+ssh://git@github.com/avandecreme/openapi-down-convert.git#654309786f68362a6ae7b03f0d76f7e24abcf9f1", + "license": "ISC", + "dependencies": { + "commander": "^9.4.1", + "js-yaml": "^4.1.0", + "typescript": "^4.8.4" + }, + "bin": { + "openapi-down-convert": "lib/src/cli.js" + } + }, "node_modules/@babel/runtime": { "version": "7.24.4", "resolved": "https://registry.npmjs.org/@babel/runtime/-/runtime-7.24.4.tgz", @@ -214,6 +232,13 @@ "integrity": "sha512-n4sx2bqL0mW1tvDf/loQ+aMX7GQD3lc3fkCMC55VFNDu/vBOabO+LTIeXKM14xK0ppk5TUGcWRjiSpIlUpghKw==", "dev": true }, + "node_modules/@types/yamljs": { + "version": "0.2.34", + "resolved": "https://registry.npmjs.org/@types/yamljs/-/yamljs-0.2.34.tgz", + "integrity": "sha512-gJvfRlv9ErxdOv7ux7UsJVePtX54NAvQyd8ncoiFqK8G5aeHIfQfGH2fbruvjAQ9657HwAaO54waS+Dsk2QTUQ==", + "dev": true, + "license": "MIT" + }, "node_modules/abort-controller": { "version": "3.0.0", "resolved": "https://registry.npmjs.org/abort-controller/-/abort-controller-3.0.0.tgz", @@ -266,8 +291,7 @@ "node_modules/argparse": { "version": "2.0.1", "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz", - "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==", - "dev": true + "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==" }, "node_modules/asynckit": { "version": "0.4.0", @@ -416,6 +440,15 @@ "node": ">= 0.8" } }, + "node_modules/commander": { + "version": "9.5.0", + "resolved": "https://registry.npmjs.org/commander/-/commander-9.5.0.tgz", + "integrity": "sha512-KRs7WVDKg86PWiuAqhDrAQnTXZKraVcCc6vFdL14qrZ/DcWwuRo7VoiYXalXO7S5GKpqYiVEwCbgFDfxNHKJBQ==", + "license": "MIT", + "engines": { + "node": "^12.20.0 || >=14" + } + }, "node_modules/concat-map": { "version": "0.0.1", "resolved": "https://registry.npmjs.org/concat-map/-/concat-map-0.0.1.tgz", @@ -757,7 +790,6 @@ "version": "4.1.0", "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.0.tgz", "integrity": "sha512-wpxZs9NoxZaJESJGIZTyDEaYpl0FKSA+FB9aJiyemKhMwkxQg63h4T1KJgUGHpTqPDNRcmmYLugrRjJlBtWvRA==", - "dev": true, "dependencies": { "argparse": "^2.0.1" }, @@ -1605,6 +1637,13 @@ "node": ">=0.10.0" } }, + "node_modules/sprintf-js": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/sprintf-js/-/sprintf-js-1.0.3.tgz", + "integrity": "sha512-D9cPgkvLlV3t3IzL0D0YLvGA9Ahk4PcvVwUbN0dSGr1aP0Nrt4AEnTUbuGvquEC0mA64Gqt1fzirlRs5ibXx8g==", + "dev": true, + "license": "BSD-3-Clause" + }, "node_modules/stickyfill": { "version": "1.1.1", "resolved": "https://registry.npmjs.org/stickyfill/-/stickyfill-1.1.1.tgz", @@ -1772,6 +1811,19 @@ "integrity": "sha1-gYT9NH2snNwYWZLzpmIuFLnZq2o=", "dev": true }, + "node_modules/typescript": { + "version": "4.9.5", + "resolved": "https://registry.npmjs.org/typescript/-/typescript-4.9.5.tgz", + "integrity": "sha512-1FXk9E2Hm+QzZQ7z+McJiHL4NW1F2EzMu9Nq9i3zAaGqibafqYwCVU6WyWAuyQRRzOlxou8xZSyXLEN8oKj24g==", + "license": "Apache-2.0", + "bin": { + "tsc": "bin/tsc", + "tsserver": "bin/tsserver" + }, + "engines": { + "node": ">=4.2.0" + } + }, "node_modules/uglify-js": { "version": "3.17.4", "resolved": "https://registry.npmjs.org/uglify-js/-/uglify-js-3.17.4.tgz", @@ -1908,6 +1960,31 @@ "integrity": "sha512-2PTINUwsRqSd+s8XxKaJWQlUuEMHJQyEuh2edBbW8KNJz0SJPwUSD2zRWqezFEdN7IzAgeuYHFUCF7o8zRdZ0A==", "dev": true }, + "node_modules/yamljs": { + "version": "0.3.0", + "resolved": "https://registry.npmjs.org/yamljs/-/yamljs-0.3.0.tgz", + "integrity": "sha512-C/FsVVhht4iPQYXOInoxUM/1ELSf9EsgKH34FofQOp6hwCPrW4vG4w5++TED3xRUo8gD7l0P1J1dLlDYzODsTQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "argparse": "^1.0.7", + "glob": "^7.0.5" + }, + "bin": { + "json2yaml": "bin/json2yaml", + "yaml2json": "bin/yaml2json" + } + }, + "node_modules/yamljs/node_modules/argparse": { + "version": "1.0.10", + "resolved": "https://registry.npmjs.org/argparse/-/argparse-1.0.10.tgz", + "integrity": "sha512-o5Roy6tNG4SL/FOkCAN6RzjiakZS25RLYFrcMttJqbdd8BWrnA+fGz57iN5Pb06pvBGvl5gQ0B48dJlslXvoTg==", + "dev": true, + "license": "MIT", + "dependencies": { + "sprintf-js": "~1.0.2" + } + }, "node_modules/yargs-parser": { "version": "20.2.9", "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-20.2.9.tgz", @@ -1930,6 +2007,15 @@ "js-yaml": "^4.1.0" } }, + "@apiture/openapi-down-convert": { + "version": "git+ssh://git@github.com/avandecreme/openapi-down-convert.git#654309786f68362a6ae7b03f0d76f7e24abcf9f1", + "from": "@apiture/openapi-down-convert@github:avandecreme/openapi-down-convert#nullable_pr", + "requires": { + "commander": "^9.4.1", + "js-yaml": "^4.1.0", + "typescript": "^4.8.4" + } + }, "@babel/runtime": { "version": "7.24.4", "resolved": "https://registry.npmjs.org/@babel/runtime/-/runtime-7.24.4.tgz", @@ -2092,6 +2178,12 @@ "integrity": "sha512-n4sx2bqL0mW1tvDf/loQ+aMX7GQD3lc3fkCMC55VFNDu/vBOabO+LTIeXKM14xK0ppk5TUGcWRjiSpIlUpghKw==", "dev": true }, + "@types/yamljs": { + "version": "0.2.34", + "resolved": "https://registry.npmjs.org/@types/yamljs/-/yamljs-0.2.34.tgz", + "integrity": "sha512-gJvfRlv9ErxdOv7ux7UsJVePtX54NAvQyd8ncoiFqK8G5aeHIfQfGH2fbruvjAQ9657HwAaO54waS+Dsk2QTUQ==", + "dev": true + }, "abort-controller": { "version": "3.0.0", "resolved": "https://registry.npmjs.org/abort-controller/-/abort-controller-3.0.0.tgz", @@ -2129,8 +2221,7 @@ "argparse": { "version": "2.0.1", "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz", - "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==", - "dev": true + "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==" }, "asynckit": { "version": "0.4.0", @@ -2250,6 +2341,11 @@ "delayed-stream": "~1.0.0" } }, + "commander": { + "version": "9.5.0", + "resolved": "https://registry.npmjs.org/commander/-/commander-9.5.0.tgz", + "integrity": "sha512-KRs7WVDKg86PWiuAqhDrAQnTXZKraVcCc6vFdL14qrZ/DcWwuRo7VoiYXalXO7S5GKpqYiVEwCbgFDfxNHKJBQ==" + }, "concat-map": { "version": "0.0.1", "resolved": "https://registry.npmjs.org/concat-map/-/concat-map-0.0.1.tgz", @@ -2515,7 +2611,6 @@ "version": "4.1.0", "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.0.tgz", "integrity": "sha512-wpxZs9NoxZaJESJGIZTyDEaYpl0FKSA+FB9aJiyemKhMwkxQg63h4T1KJgUGHpTqPDNRcmmYLugrRjJlBtWvRA==", - "dev": true, "requires": { "argparse": "^2.0.1" } @@ -3117,6 +3212,12 @@ "integrity": "sha512-itJW8lvSA0TXEphiRoawsCksnlf8SyvmFzIhltqAHluXd88pkCd+cXJVHTDwdCr0IzwptSm035IHQktUu1QUMg==", "dev": true }, + "sprintf-js": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/sprintf-js/-/sprintf-js-1.0.3.tgz", + "integrity": "sha512-D9cPgkvLlV3t3IzL0D0YLvGA9Ahk4PcvVwUbN0dSGr1aP0Nrt4AEnTUbuGvquEC0mA64Gqt1fzirlRs5ibXx8g==", + "dev": true + }, "stickyfill": { "version": "1.1.1", "resolved": "https://registry.npmjs.org/stickyfill/-/stickyfill-1.1.1.tgz", @@ -3251,6 +3352,11 @@ "integrity": "sha1-gYT9NH2snNwYWZLzpmIuFLnZq2o=", "dev": true }, + "typescript": { + "version": "4.9.5", + "resolved": "https://registry.npmjs.org/typescript/-/typescript-4.9.5.tgz", + "integrity": "sha512-1FXk9E2Hm+QzZQ7z+McJiHL4NW1F2EzMu9Nq9i3zAaGqibafqYwCVU6WyWAuyQRRzOlxou8xZSyXLEN8oKj24g==" + }, "uglify-js": { "version": "3.17.4", "resolved": "https://registry.npmjs.org/uglify-js/-/uglify-js-3.17.4.tgz", @@ -3355,6 +3461,27 @@ "integrity": "sha512-2PTINUwsRqSd+s8XxKaJWQlUuEMHJQyEuh2edBbW8KNJz0SJPwUSD2zRWqezFEdN7IzAgeuYHFUCF7o8zRdZ0A==", "dev": true }, + "yamljs": { + "version": "0.3.0", + "resolved": "https://registry.npmjs.org/yamljs/-/yamljs-0.3.0.tgz", + "integrity": "sha512-C/FsVVhht4iPQYXOInoxUM/1ELSf9EsgKH34FofQOp6hwCPrW4vG4w5++TED3xRUo8gD7l0P1J1dLlDYzODsTQ==", + "dev": true, + "requires": { + "argparse": "^1.0.7", + "glob": "^7.0.5" + }, + "dependencies": { + "argparse": { + "version": "1.0.10", + "resolved": "https://registry.npmjs.org/argparse/-/argparse-1.0.10.tgz", + "integrity": "sha512-o5Roy6tNG4SL/FOkCAN6RzjiakZS25RLYFrcMttJqbdd8BWrnA+fGz57iN5Pb06pvBGvl5gQ0B48dJlslXvoTg==", + "dev": true, + "requires": { + "sprintf-js": "~1.0.2" + } + } + } + }, "yargs-parser": { "version": "20.2.9", "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-20.2.9.tgz", diff --git a/package.json b/package.json index 8df897d3..a8bbca46 100644 --- a/package.json +++ b/package.json @@ -17,13 +17,16 @@ "preview:platform": "npm run build:platform && npx @redocly/cli preview-docs dist/platform.yml", "preview:internal": "npm run build:internal && npx @redocly/cli preview-docs dist/internal.yml", "preview:scheduler": "npm run build:scheduler && npx @redocly/cli preview-docs cycle-scheduler-api", - "preview:ial": "npm run build:ial && npx @redocly/cli preview-docs cycle-ial" + "preview:ial": "npm run build:ial && npx @redocly/cli preview-docs cycle-ial", + "downconvert:platform": "npm run build:platform && npx tsx ./util/downconvert.ts" }, "author": "Petrichor Holdings, Inc.", "license": "Apache-2.0", "devDependencies": { "@apidevtools/json-schema-ref-parser": "^11.5.4", "@redocly/cli": "1.11.0", - "@types/node": "^20.12.7" + "@types/node": "^20.12.7", + "@types/yamljs": "^0.2.34", + "yamljs": "^0.3.0" } } diff --git a/stackspec/schema/StackSpecContainer.yml b/stackspec/schema/StackSpecContainer.yml index 65c2c305..a114fe02 100644 --- a/stackspec/schema/StackSpecContainer.yml +++ b/stackspec/schema/StackSpecContainer.yml @@ -11,6 +11,7 @@ properties: type: string description: The human-readable name of this container. image: + x-ogen-name: StackSpecContainerImageProperty description: Details about the image used for this container. oneOf: - $ref: StackSpecContainerImage.yml diff --git a/stackspec/schema/StackSpecContainerConfigDeploy.yml b/stackspec/schema/StackSpecContainerConfigDeploy.yml index 25bcf36d..80e2a059 100644 --- a/stackspec/schema/StackSpecContainerConfigDeploy.yml +++ b/stackspec/schema/StackSpecContainerConfigDeploy.yml @@ -155,15 +155,7 @@ properties: - type: array description: Signals that should be sent to the container on shutdown. items: - type: string - enum: - - SIGTERM - - SIGINT - - SIGUSR1 - - SIGUSR2 - - SIGHUB - - SIGKILL - - SIGQUIT + $ref: ../../components/schemas/containers/config/ShutdownSignal.yml - $ref: StackVariable.yml - $ref: StackVariable.yml startup: diff --git a/stackspec/schema/StackSpecContainerConfigNetwork.yml b/stackspec/schema/StackSpecContainerConfigNetwork.yml index b2c9dc08..66e310db 100644 --- a/stackspec/schema/StackSpecContainerConfigNetwork.yml +++ b/stackspec/schema/StackSpecContainerConfigNetwork.yml @@ -1,4 +1,5 @@ title: StackSpecContainerConfigNetwork +x-ogen-name: StackSpecContainerConfigNetwork description: Stack configuration options related to the container's network. type: object required: diff --git a/stackspec/schema/services/loadbalancer/types/StackSpecDefaultLbType.yml b/stackspec/schema/services/loadbalancer/types/StackSpecDefaultLbType.yml index a025ccc5..d27eb81a 100644 --- a/stackspec/schema/services/loadbalancer/types/StackSpecDefaultLbType.yml +++ b/stackspec/schema/services/loadbalancer/types/StackSpecDefaultLbType.yml @@ -20,5 +20,4 @@ properties: oneOf: - $ref: ./haproxy/StackSpecHaProxyConfig.yml - $ref: ./v1/StackSpecV1LbConfig.yml - - type: "null" diff --git a/stackspec/schema/services/loadbalancer/types/v1/StackSpecV1LbRouterConfig.yml b/stackspec/schema/services/loadbalancer/types/v1/StackSpecV1LbRouterConfig.yml index 66161a09..d19c8715 100644 --- a/stackspec/schema/services/loadbalancer/types/v1/StackSpecV1LbRouterConfig.yml +++ b/stackspec/schema/services/loadbalancer/types/v1/StackSpecV1LbRouterConfig.yml @@ -95,7 +95,6 @@ properties: - type: integer - $ref: ../../../../StackVariable.yml destination_prioritization: - default: null oneOf: - type: string description: > diff --git a/util/downconvert.ts b/util/downconvert.ts new file mode 100644 index 00000000..c04d21b0 --- /dev/null +++ b/util/downconvert.ts @@ -0,0 +1,436 @@ +type OpenAPISpec31 = { + openapi: "3.1.0"; + components?: ComponentsObject; + paths?: Record; + webhooks?: Record; + [key: string]: any; +}; + +type OpenAPISpec30 = { + openapi: "3.0.1"; + components?: ComponentsObject; + paths?: Record; + [key: string]: any; +}; + +type ComponentsObject = { + schemas?: Record; + [key: string]: any; +}; + +type PathItemObject = { + [method: string]: OperationObject; +}; + +type OperationObject = { + requestBody?: { + content?: ContentObject; + [key: string]: any; + }; + responses?: Record; + parameters?: Array<{ + schema?: SchemaObject; + [key: string]: any; + }>; + [key: string]: any; +}; + +type ContentObject = Record; + +type MediaTypeObject = { + schema?: SchemaObject; + [key: string]: any; +}; + +type SchemaObject = { + type?: string | string[]; + nullable?: boolean; + oneOf?: SchemaObject[]; + anyOf?: SchemaObject[]; + allOf?: SchemaObject[]; + $ref?: string; + properties?: Record; + items?: SchemaObject; + required?: string[]; + [key: string]: any; +}; + +class Schema { + type?: string; + nullable?: boolean; + oneOf?: Schema[]; + anyOf?: Schema[]; + allOf?: Schema[]; + $ref?: string; + properties?: Record; + items?: Schema; + required?: string[]; + additionalProperties?: Schema; + discriminator?: { + propertyName: string; + mapping?: Record; + }; + [key: string]: any; + + constructor(schema: Partial) { + Object.assign(this, schema); + + if (Array.isArray(schema.type)) { + this.handleTypeArray(schema.type); + } + + if (schema.oneOf) { + this.oneOf = schema.oneOf.map((entry) => new Schema(entry)); + } + if (schema.anyOf) { + this.anyOf = schema.anyOf.map((entry) => new Schema(entry)); + } + if (schema.allOf) { + this.allOf = schema.allOf.map((entry) => new Schema(entry)); + } + if (schema.properties) { + this.properties = {}; + for (const key in schema.properties) { + this.properties[key] = new Schema(schema.properties[key]); + } + } + if (schema.items) { + this.items = new Schema(schema.items); + } + if (schema.additionalProperties) { + this.additionalProperties = new Schema(schema.additionalProperties); + } + } + + // Handle `type` when provided as an array + handleTypeArray(types: string[]) { + if (types.includes("null")) { + this.nullable = true; + this.type = types.filter((type) => type !== "null")[0] || "object"; + } else { + this.type = types[0]; + } + } + + // Method to adjust the schema for OpenAPI 3.0.3 compatibility + adjust(schemaMap: Record) { + this.removeUnsupportedProperties(); + this.handleConstAsEnum(); + this.handleNullType(); + this.handleAnyOfWithNull(); + this.handleOneOfWithNull(); + this.flattenIdenticalReferences(schemaMap); + this.adjustNestedSchemas(schemaMap); + } + + // Remove unsupported properties in OpenAPI 3.0.3 + removeUnsupportedProperties() { + delete this.$schema; + delete this.$id; + delete this.$comment; + delete this.unevaluatedProperties; + delete this.patternProperties; + delete this.contentMediaType; + delete this.contentEncoding; + delete this.examples; // Remove the `examples` property + } + + // Handle `const` by converting it to `enum` + handleConstAsEnum() { + if (this.const !== undefined) { + this.enum = [this.const]; + delete this.const; + } + } + + // 🔹 Convert `type: "null"` to `type: "object", nullable: true` + handleNullType() { + if (this.type === "null") { + this.type = "object"; + this.nullable = true; + } + } + + // Handle `anyOf` containing `null` and a reference or another type + handleAnyOfWithNull() { + if (this.anyOf) { + let hasNullType = false; + let nonNullEntry: Schema | null = null; + + // Check for `null` type in `anyOf` + this.anyOf.forEach((entry) => { + if (entry.type === "null") { + hasNullType = true; + } else { + nonNullEntry = entry; + } + }); + + // If both `null` and another type are present, make the schema nullable and use `allOf` for reference + if (hasNullType && nonNullEntry) { + this.nullable = true; + + if ((nonNullEntry as Schema).$ref) { + // Convert `anyOf` to `allOf` with the reference + this.allOf = [{ $ref: (nonNullEntry as Schema).$ref } as Schema]; + } else { + // Otherwise, retain all properties of the non-null entry + Object.assign(this, nonNullEntry); + } + + delete this.anyOf; + } + } + } + + // Handle `oneOf` containing `null` and another type + handleOneOfWithNull() { + // Do not modify `oneOf` if a discriminator is present + if (this.discriminator) { + return; + } + + if (this.oneOf) { + let hasNullType = false; + let nonNullEntry: Schema | null = null; + + // Iterate through the `oneOf` entries + this.oneOf.forEach((entry) => { + if (entry.type === "null") { + hasNullType = true; + } else { + nonNullEntry = entry; + } + }); + + // If both `null` and another type are present + if (hasNullType && nonNullEntry) { + // Set nullable to true + this.nullable = true; + + // Retain all properties of the non-null entry (type, enum, description, etc.) + for (const key in nonNullEntry as Schema) { + if (key !== "type" && key !== "nullable") { + (this as any)[key] = nonNullEntry[key]; + } + } + + // Assign the type of the non-null entry + this.type = (nonNullEntry as Schema).type; + + // If there's an enum, retain it + if ((nonNullEntry as Schema).enum) { + this.enum = (nonNullEntry as Schema).enum; + } + + delete this.oneOf; + } + } + } + + // Flatten `oneOf` or `anyOf` if all `$ref` point to the same primitive type + flattenIdenticalReferences(schemaMap: Record) { + // Do not modify `oneOf` or `anyOf` if a discriminator is present + if (this.discriminator) { + return; + } + + const keywords = ["oneOf", "anyOf"] as const; + + keywords.forEach((keyword) => { + if (this[keyword]) { + const entries = this[keyword]!; + let primitiveType: string | null = null; + let hasNullType = false; + + // Check each entry in `oneOf` or `anyOf` + entries.forEach((entry) => { + if (entry.$ref) { + const refSchemaName = entry.$ref.split("/").pop()!; + const refSchema = schemaMap[refSchemaName]; + + if (refSchema) { + if (typeof refSchema.type === "string") { + if (!primitiveType) { + primitiveType = refSchema.type; + } else if (primitiveType !== refSchema.type) { + primitiveType = null; // Different types found, cannot flatten + } + } + } + } else if (entry.type === "null") { + hasNullType = true; + } else if (typeof entry.type === "string") { + if (!primitiveType) { + primitiveType = entry.type; + } else if (primitiveType !== entry.type) { + primitiveType = null; // Different types found, cannot flatten + } + } + }); + + // If all references point to the same primitive type + if (primitiveType) { + this.type = primitiveType; + if (hasNullType) { + this.nullable = true; + } + delete this[keyword]; + } + } + }); + } + + // Adjust nested schemas recursively + adjustNestedSchemas(schemaMap: Record) { + if (this.properties) { + Object.values(this.properties).forEach((property) => { + property.adjust(schemaMap); + }); + } + + if (this.items) { + this.items.adjust(schemaMap); + } + + if (this.additionalProperties) { + this.additionalProperties.adjust(schemaMap); + } + + // Recursively adjust oneOf, anyOf, allOf entries + const keywords = ["oneOf", "anyOf", "allOf"] as const; + keywords.forEach((keyword) => { + if (this[keyword]) { + this[keyword] = this[keyword]!.map((entry) => { + // Ensure entry is converted to a Schema instance before adjustment + const schemaEntry = + entry instanceof Schema ? entry : new Schema(entry); + schemaEntry.adjust(schemaMap); + return schemaEntry; + }); + } + }); + } +} + +// Function to downconvert OpenAPI 3.1 to 3.0.3 +export function downconvertOpenAPI31To30(spec: OpenAPISpec31): OpenAPISpec30 { + const convertedSpec: OpenAPISpec30 = { ...spec, openapi: "3.0.1" }; + + // Map to store schemas for resolving $ref types + const schemaMap: Record = convertedSpec.components?.schemas + ? Object.fromEntries( + Object.entries(convertedSpec.components.schemas).map(([key, value]) => [ + key, + new Schema(value), + ]) + ) + : {}; + + // Adjust schema properties in components + if (convertedSpec.components?.schemas) { + for (const schemaName in convertedSpec.components.schemas) { + const schema = schemaMap[schemaName]; + schema.adjust(schemaMap); + convertedSpec.components.schemas[schemaName] = schema; + } + } + + // Adjust paths + if (convertedSpec.paths) { + for (const path in convertedSpec.paths) { + const pathItem = convertedSpec.paths[path]; + for (const method in pathItem) { + const operation = pathItem[method]; + + // Handle requestBody content + if (operation.requestBody?.content) { + Object.values(operation.requestBody.content).forEach((mediaType) => { + if (mediaType.schema) { + const schema = new Schema(mediaType.schema); + schema.adjust(schemaMap); + mediaType.schema = schema; + } + }); + } + + // Handle response content + if (operation.responses) { + for (const response in operation.responses) { + if (operation.responses[response]?.content) { + Object.values(operation.responses[response].content).forEach( + (mediaType) => { + if (mediaType.schema) { + const schema = new Schema(mediaType.schema); + schema.adjust(schemaMap); + mediaType.schema = schema; + } + } + ); + } + } + } + + // Handle parameters + if (operation.parameters) { + operation.parameters.forEach((parameter) => { + if (parameter.schema) { + const schema = new Schema(parameter.schema); + schema.adjust(schemaMap); + parameter.schema = schema; + } + }); + } + } + } + } + + return convertedSpec; +} + +import { promises as fs } from "fs"; +import path from "path"; +import YAML from "yamljs"; + +async function readYamlFile(filePath: string): Promise { + try { + // Resolve the full path to ensure it works with relative paths + const fullPath = path.resolve(filePath); + + // Read the YAML file asynchronously + const fileContents = await fs.readFile(fullPath, "utf8"); + + // Parse YAML into JSON + const parsedData = YAML.parse(fileContents); + + return parsedData; + } catch (err) { + if (err && typeof err === "object" && "message" in err) { + throw new Error(`Error reading or parsing YAML file: ${err.message}`); + } + throw err; + } +} + +async function writeJsonToFile(filePath: string, data: object): Promise { + try { + // Resolve the full path to ensure it works with relative paths + const fullPath = path.resolve(filePath); + + // Convert the data to a JSON string + const jsonString = JSON.stringify(data, null, 2); // Pretty print with 2-space indentation + + // Write the JSON string to the specified file asynchronously + await fs.writeFile(fullPath, jsonString, "utf8"); + console.log(`Successfully wrote to ${fullPath}`); + } catch (err) { + if (err && typeof err === "object" && "message" in err) { + throw new Error(`Error writing JSON to file: ${err.message}`); + } + throw err; + } +} + +readYamlFile("./dist/platform.yml") + .then((r) => downconvertOpenAPI31To30(r as any)) + .then((spec) => writeJsonToFile("./dist/platform-3.0.3.json", spec)); diff --git a/util/tsconfig.json b/util/tsconfig.json new file mode 100644 index 00000000..af2c7e74 --- /dev/null +++ b/util/tsconfig.json @@ -0,0 +1,20 @@ +{ + "compilerOptions": { + "target": "ESNext", + "module": "NodeNext", + "lib": [ + "ESNext" + ], + "outDir": "./dist", + "strict": true, + "esModuleInterop": true, + "moduleResolution": "nodenext", + "resolveJsonModule": true, + "skipLibCheck": true, + "forceConsistentCasingInFileNames": true, + }, + "include": ["./downconvert.ts"], + "exclude": [ + "dist" + ] +} \ No newline at end of file