2023-08-22 22:23:54 +00:00
|
|
|
// Copyright (c) HashiCorp, Inc.
|
|
|
|
|
// SPDX-License-Identifier: BUSL-1.1
|
|
|
|
|
|
2023-08-11 19:52:51 +00:00
|
|
|
// The protohcl package aims to define a canonical way to translate between
|
|
|
|
|
// protobuf and HCL encodings of data.
|
|
|
|
|
//
|
|
|
|
|
// Similar to google.golang.org/protobuf/encoding/protojson it intends to be
|
|
|
|
|
// opinionated about what the canonical HCL representation of a protobuf type
|
|
|
|
|
// should be.
|
|
|
|
|
//
|
|
|
|
|
// As HCL is a user centric data format as opposed to JSON/Protobuf which
|
|
|
|
|
// are intended to be used more by machines, efficiency is not a primary goal
|
|
|
|
|
// of this package as it is expected that users are either doing the encoding to and
|
|
|
|
|
// decoding from HCL at the edge (such as within the Consul CLI) or that even
|
|
|
|
|
// when done on servers, the rate that servers perform these translations should
|
|
|
|
|
// be low enough to have any inefficiency produce a tangible performance impact.
|
|
|
|
|
//
|
|
|
|
|
// HCL has two different syntaxes that could be used to represent data: attribute and block
|
|
|
|
|
//
|
|
|
|
|
// This implementation chooses to represent primitive values, enums and the well known wrapper types and
|
|
|
|
|
// collections of these values (maps and repeated fields) with attribute syntax. Other messages and collections
|
|
|
|
|
// with message value types will be represented with block syntax for example
|
|
|
|
|
//
|
|
|
|
|
// message Foo {
|
|
|
|
|
// map<string, int32> map_of_ints = 1;
|
|
|
|
|
// map<string, OtherMessage> map_of_messages = 2;
|
|
|
|
|
// }
|
|
|
|
|
//
|
|
|
|
|
// would have HCL like:
|
|
|
|
|
//
|
|
|
|
|
// map_of_ints = {
|
|
|
|
|
// "foo": 1,
|
|
|
|
|
// "bar": 2,
|
|
|
|
|
// }
|
|
|
|
|
// map_of_messages "foo" {
|
|
|
|
|
// ...other fields
|
|
|
|
|
// }
|
|
|
|
|
// map_of_messages "bar" {
|
|
|
|
|
// ...other fields
|
|
|
|
|
// }
|
|
|
|
|
//
|
|
|
|
|
// Similar goes for list of primitives vs list of messages (except the block syntax uses no labels). The differences
|
|
|
|
|
// between primitive fields outside of a collection and a message field really just amounts to not having to specify
|
|
|
|
|
// the "=" between the field name and the "{" character.
|
|
|
|
|
//
|
|
|
|
|
// Field Mapping
|
|
|
|
|
// | proto3 | HCL Type | example | notes |
|
|
|
|
|
// |------------------------+---------------+---------+---------------------------------------------------------------------------------+
|
|
|
|
|
// | message | Object | | Represented as a block |
|
|
|
|
|
// | enum | String | | |
|
|
|
|
|
// | map<K,V> | Map | | All keys are converted to/from strings. |
|
|
|
|
|
// | repeated V | List | | |
|
|
|
|
|
// | bool | Bool | | |
|
|
|
|
|
// | string | String | | |
|
|
|
|
|
// | bytes | base64 String | | |
|
|
|
|
|
// | int32, fixed32, uint32 | Number | | |
|
|
|
|
|
// | int64, fixed64, uint64 | Number | | |
|
|
|
|
|
// | float, double | Number | | |
|
|
|
|
|
//
|
|
|
|
|
// ----- Well Known Types -----
|
|
|
|
|
//
|
|
|
|
|
// | Any | Object | | |
|
|
|
|
|
// | Timestamp | String | | RFC 3339 compliant |
|
|
|
|
|
// | Duration | String | | String form is what would be accepted by time.ParseDuration |
|
|
|
|
|
// | Struct | Map | | |
|
|
|
|
|
// | Empty | Object | | An object with no fields |
|
|
|
|
|
// | BoolValue | Bool | | Mostly the same as a regular bool except null values in the HCL are preserved |
|
|
|
|
|
// | BytesValue | Bytes | | Mostly the same as a regular bytes except null values in the HCL are preserved |
|
|
|
|
|
// | StringValue | String | | Mostly the same as a regular string except null values in the HCL are preserved |
|
|
|
|
|
// | FloatValue | Number | | Mostly the same as a regular float except null values in the HCL are preserved |
|
|
|
|
|
// | DoubleValue | Number | | Mostly the same as a regular double except null values in the HCL are preserved |
|
|
|
|
|
// | Int32Value | Number | | Mostly the same as a regular int32 except null values in the HCL are preserved |
|
|
|
|
|
// | UInt32Value | Number | | Mostly the same as a regular uint32 except null values in the HCL are preserved |
|
|
|
|
|
// | Int64Value | Number | | Mostly the same as a regular int64 except null values in the HCL are preserved |
|
|
|
|
|
// | UInt64Value | Number | | Mostly the same as a regular uint64 except null values in the HCL are preserved |
|
|
|
|
|
// | FieldMask | String | | Each string of the FieldMask will be joined with a '.' |
|
|
|
|
|
//
|
|
|
|
|
|
|
|
|
|
package protohcl
|
