Add downconverter script

README.md

@@ -1,43 +1,111 @@
 # Cycle API Spec
 
-<picture>
+<a href="https://cycle.io">
+<picture class="red">
   <source media="(prefers-color-scheme: dark)" srcset="https://cycle.io/global/resources/images/logos/cycle-logo-white.svg">
   <source media="(prefers-color-scheme: light)" srcset="https://static.cycle.io/icons/logo/cycle-logo-fullcolor.svg">
-  <img alt="cycle" src="https://static.cycle.io/icons/logo/cycle-logo-fullcolor.svg">
+  <img alt="cycle" width="300px" src="https://static.cycle.io/icons/logo/cycle-logo-fullcolor.svg">
 </picture>
+</a>
 
-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`.

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

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

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

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

components/schemas/environments/EnvironmentFeatures.yml

@@ -19,6 +19,6 @@ properties:
         type: string
         enum:
           - limited
-          - standard
+          - basic
           - premium
           - enterprise

components/schemas/environments/services/DiscoveryEnvironmentService.yml

@@ -5,7 +5,6 @@ required:
   - enable
   - container_id
   - high_availability
-  - config
 properties:
   enable:
     type: boolean

components/schemas/environments/services/LoadBalancerEnvironmentService.yml

@@ -5,7 +5,6 @@ required:
   - enable
   - container_id
   - high_availability
-  - config
 properties:
   enable:
     type: boolean

components/schemas/environments/services/SchedulerEnvironmentService.yml

@@ -7,7 +7,6 @@ required:
   - enable
   - container_id
   - high_availablity
-  # - config
 properties:
   enable:
     type: boolean

components/schemas/environments/services/VpnEnvironmentService.yml

@@ -5,7 +5,6 @@ required:
   - enable
   - container_id
   - high_availability
-  - config
 properties:
   enable:
     type: boolean

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"

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: >

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. 

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

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.
 

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

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/<IMAGE ID>/upload?hub-id=<HUB ID>&token=<TOKEN>`.
+required:
+  - type
+  - details
 properties:
   type:
     type: string

components/schemas/images/sources/BucketImageSourceType.yml

@@ -1,8 +1,8 @@
 title: BucketImageSource
 type: object
 required:
-  - id
-  - origin
+  - type
+  - details
 properties:
   type:
     type: string

components/schemas/images/sources/DirectImageSourceType.yml

@@ -1,8 +1,8 @@
 title: DirectImageSource
 type: object
 required:
-  - id
-  - origin
+  - type
+  - details
 properties:
   type:
     type: string

components/schemas/images/sources/StackImageSourceType.yml

@@ -1,8 +1,8 @@
 title: StackImageSource
 type: object
 required:
-  - id
-  - origin
+  - type
+  - details
 properties:
   type:
     type: string

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:

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

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

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:

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: