Update HCS Schema Files #1914
Draft
Update HCS Schema Files #1914
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Run swagger code generator (`swagger-codegen-cli`) on HCS schema (version 2.5) based on Windows Server 2022 (OS build 20348) files to regenerate the hcsschema package (`internal/hcs/schema2`). See for schema version information. https://learn.microsoft.com/en-us/virtualization/api/hcs/schemareference#schema-version-map (The files show the API version as 2.4, that is controlled by the OpenAPI schema generator, which we have no control over.) Change adds several new schema objects and fields, and updates the types of other fields (eg, `hcsschema.ConsoleSize` is now a `uint16` instead of `int32`). Fix acronym capitalization. Add `internal/hcs/schema2/doc.go` to describe package design considerations, add helper functions, and list files that are manually updated. Added `*_lookup.go` files to augment certain enum types with conversion functions. This is specifically for integer-valued enums, which OpenAPI strips information from in the spec, as well as common enums (ie, `OSType` and `SystemType`) which we convert from strings. Deleted duplicate files, as well as swagger-specific ancillary files (ie, `internal/hcs/schema2/configuration.go`, created by: https://github.com/swagger-api/swagger-codegen/blob/v2.4.32/modules/swagger-codegen/src/main/resources/go/configuration.mustache) Switch from `interface{}` to `json.RawMessage` globally within package to simplify (un)marshalling and pre-compute JSON message components. Add comment to (mostly string) fields with the expected pattern. Signed-off-by: Hamza El-Saawy <[email protected]>
Update package to use new `hcsshema` (`internal/hcs/schema2`) package. Changes are minimal: - Use new constants (eg, `hcsschema.ModifyRequestType_ADD` instead of `guestrequest.RequestTypeAdd`) - Rename certain structs (eg, `hcsschema.VirtualMachineMemory` instead of `hcsschema.Memory2`) - Update certain field types (eg, `uint16` for `hcsschema.SystemTime` fields) Updates to `internal\protocol\guestrequest` and `internal\protocol\guestresource` are deferred for future work, when guest protocol definitions and logic (in `internal\guest\prot` and `internal\guest\bridge`) can be be fully merged with the host code in `internal\hcs\schema2` and `internal\gcs`. Signed-off-by: Hamza El-Saawy <[email protected]>
helsaawy
force-pushed
the
swagger-gen
branch
from
4d77c84
to
6d73fb4
Compare
|
a lot of schema definitions are not currently being used. Is the idea to define them anyway for potential 3rd party integrations or? |
we dont really have control over what is generated, since we get everything defined in the schema file |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
HCS schema v2 files (
internal/hcs/schema2) haven't been updated in a while, are missing several types, do not define enum values (eg, ModifyResourceType values are manually defined ininternal\protocol\guestresource), and default toint32for all integer-valued fields (eg, hcsschema.ConsoleSize should haveuint16fields)).This PR is split into 2 PRs:
swagger-codegen-cli) on HCS schema version 2.5 (based on Windows Server 2022 (OS build 20348)) files to regenerate the hcsschema package (internal/hcs/schema2). Additionally, add helper functions and manual updates to the package.Additionally, this PR adds a manifest of the files changed (and added) to the schema package (in
doc.go), so manual updates can be re-applied if the schema files are re-created in the future.Note: The files show the API version as 2.4, that is controlled by the OpenAPI schema generator, which we have no control over.
Additionally, even though schema version 2.5 fields are added, since the API is versioned, no new behavior is introduced when making requests.
The major changes within
internal/hcs/schema2are:Processor2is now VirtualMachineProcessor).hcsschema.ConsoleSizeis now auint16instead ofint32). This doesn't apply to integer arrays because of limitations in swagger codegen).internal/hcs/schema2/doc.goto describe package design considerations, add helper functions, and list files that have been manually updated.*_lookup.gofiles to augment certain enum types with conversion functions. This is specifically for integer-valued enums, which OpenAPI strips information from in the spec, as well as common enums (ie,OSTypeandSystemType) which we convert from strings.*_extra.go) files for creating certain request messages.internal/hcs/schema2/configuration.go, which is never used).interface{}to*json.RawMessageglobally within package to simplify (un)marshalling, and reduce the number of manual updates needed, since certain instances ofinterface{}will need it.The generated schema files (re)define types and values manually created in
internal\protocol\guestrequestandinternal\protocol\guestresource, but the latter are left for a future PR to consolidate/remove.