Documentation
¶
Overview ¶
Package ctypb aims to provide a bidirectional bridge between comparable cty and protocol buffers concepts.
"cty" (see-tie) is, in a sense, a reflection API for a language that doesn't exist. It aims to provide a dynamic type system which preserves a set of useful invariants that calling applications can rely on when using cty as a building-block for data whose structure isn't predictable at compile time.
Protocol buffers is a serialization format and associated schema language intended for transmitting messages between systems, often in an RPC style. Protocol buffers typically encourages a static definition of types written in a schema, though it is in principle possible to also define a schema at runtime. Either way, protocol buffers messages are not self-describing so a schema is required to parse one.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func FromProtobufMessage ¶
func FromProtobufMessage(msg protoreflect.Message) (cty.Value, error)
FromProtobufMessage converts the given message to an equivalent cty.Value, which will always be of an object type.
Specifically, the result is guaranteed to conform to the type that ImpliedTypeForMessageDesc would've returned if given the message descriptor that's associated with the given Message.
Note that FromProtobufMessage takes a protoreflect.Message rather than a proto.Message value directly. You can obtain a protoreflect.Message value from a proto.Message value by calling its ProtoReflect method.
func ImpliedTypeForMessageDesc ¶
func ImpliedTypeForMessageDesc(desc protoreflect.MessageDescriptor) (cty.Type, error)
ImpliedTypeForMessageDesc returns a cty.Type which corresponds to the given protocol buffers message descriptor.
The result will always be an object type, whose attributes each correspond to fields of the message descriptor. The types of those attributes will depend on the definitions of each field.
The conversion from protobuf schema to cty is lossy, because cty and protobuf do not have all concepts in common. In particular, the conversion will treat "oneOf" definitions as a set of normal fields where only one can be non-null by convention, and all of the specific protocol buffers numeric types will be generalized to cty.Number.
Protocol buffers compatibility rules do not necessarily translate directly to cty: adding new fields to an existing message type will cause the resulting object type to be non-equal to the previous object type. Whether that is important will depend on what the calling application intends to do with the resulting type.
If ImpliedTypeForMessageDesc returns an error then it might be a cty.PathError referring to a specific sub-path within the generated type.
func ToProtobufMessage ¶
func ToProtobufMessage(obj cty.Value, into protoreflect.Message) error
ToProtobufMessage writes the values from the given value into the fields of the given protobuf message.
The given value must have an object type matching what ImpliedTypeForMessageDesc would return for the message descriptor associated with the message given in "into", or else decoding will fail.
The types in the protocol buffers type system can have a smaller range than the corresponding cty types we convert from, so this function might return an error if the given values are out of range. In those cases, the returned error will be a cty.PathError with a message written to be understood by an end-user who provided whatever data was converted to cty.Value, without mentioning protobuf implementation details.
In case of any error, the given message may be partially updated.
Protocol buffers has no concept of an unknown value, so ToProtobufMessage will return an error if there are any unknown values in the given object. Don't pass marked values to ToProtobufMessage; it will panic if it encounters any values that are marked.
Types ¶
This section is empty.
Source Files