converter

package
v1.26.0-rc.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 27, 2024 License: MIT Imports: 18 Imported by: 158

Documentation

Index

Examples

Constants

View Source 
const (
	// MetadataEncoding is "encoding"
	MetadataEncoding = "encoding"
	// MetadataMessageType is "messageType"
	MetadataMessageType = "messageType"
	// MetadataEncodingBinary is "binary/plain"
	MetadataEncodingBinary = "binary/plain"
	// MetadataEncodingJSON is "json/plain"
	MetadataEncodingJSON = "json/plain"
	// MetadataEncodingNil is "binary/null"
	MetadataEncodingNil = "binary/null"
	// MetadataEncodingProtoJSON is "json/protobuf"
	MetadataEncodingProtoJSON = "json/protobuf"
	// MetadataEncodingProto is "binary/protobuf"
	MetadataEncodingProto = "binary/protobuf"
)

Variables

View Source 
var (
	// ErrMetadataIsNotSet is returned when metadata is not set.
	ErrMetadataIsNotSet = errors.New("metadata is not set")
	// ErrEncodingIsNotSet is returned when payload encoding metadata is not set.
	ErrEncodingIsNotSet = errors.New("payload encoding metadata is not set")
	// ErrEncodingIsNotSupported is returned when payload encoding is not supported.
	ErrEncodingIsNotSupported = errors.New("payload encoding is not supported")
	// ErrUnableToEncode is returned when unable to encode.
	ErrUnableToEncode = errors.New("unable to encode")
	// ErrUnableToDecode is returned when unable to decode.
	ErrUnableToDecode = errors.New("unable to decode")
	// ErrUnableToSetValue is returned when unable to set value.
	ErrUnableToSetValue = errors.New("unable to set value")
	// ErrUnableToFindConverter is returned when unable to find converter.
	ErrUnableToFindConverter = errors.New("unable to find converter")
	// ErrTypeNotImplementProtoMessage is returned when value doesn't implement proto.Message.
	ErrTypeNotImplementProtoMessage = errors.New("type doesn't implement proto.Message")
	// ErrValuePtrIsNotPointer is returned when proto value is not a pointer.
	ErrValuePtrIsNotPointer = errors.New("not a pointer type")
	// ErrValuePtrMustConcreteType is returned when proto value is of interface type.
	ErrValuePtrMustConcreteType = errors.New("must be a concrete type, not interface")
	// ErrTypeIsNotByteSlice is returned when value is not of *[]byte type.
	ErrTypeIsNotByteSlice = errors.New("type is not *[]byte")
)

Functions

func DecodeCommonFailureAttributes added in v1.20.0 

func DecodeCommonFailureAttributes(dc DataConverter, failure *failurepb.Failure)

DecodeCommonFailureAttributes unpacks failure attributes from a stored payload, if present.

func EncodeCommonFailureAttributes added in v1.20.0 

func EncodeCommonFailureAttributes(dc DataConverter, failure *failurepb.Failure) error

EncodeCommonFailureAttributes packs failure attributes to a payload so that they flow through a dataconverter.

func NewFailureGRPCClientInterceptor added in v1.20.0 

func NewFailureGRPCClientInterceptor(options NewFailureGRPCClientInterceptorOptions) (grpc.UnaryClientInterceptor, error)

NewFailureGRPCClientInterceptor returns a GRPC Client Interceptor that will mimic the encoding that the SDK system would perform when configured with a FailureConverter with the EncodeCommonAttributes option set. When combining this with NewPayloadCodecGRPCClientInterceptor you should ensure that NewFailureGRPCClientInterceptor is before NewPayloadCodecGRPCClientInterceptor in the chain.

func NewPayloadCodecGRPCClientInterceptor added in v1.14.0 

func NewPayloadCodecGRPCClientInterceptor(options PayloadCodecGRPCClientInterceptorOptions) (grpc.UnaryClientInterceptor, error)

NewPayloadCodecGRPCClientInterceptor returns a GRPC Client Interceptor that will mimic the encoding that the SDK system would perform when configured with a matching EncodingDataConverter. Note: This approach does not support use cases that rely on the ContextAware DataConverter interface as workflow context is not available at the GRPC level.

func NewPayloadCodecHTTPHandler added in v1.14.0 

func NewPayloadCodecHTTPHandler(e ...PayloadCodec) http.Handler

NewPayloadCodecHTTPHandler creates a http.Handler for a PayloadCodec. This can be used to provide a remote data converter.

Types

type ByteSlicePayloadConverter 

type ByteSlicePayloadConverter struct {
}

ByteSlicePayloadConverter pass through []byte to Data field in payload.

func NewByteSlicePayloadConverter 

func NewByteSlicePayloadConverter() *ByteSlicePayloadConverter

NewByteSlicePayloadConverter creates new instance of ByteSlicePayloadConverter.

func (*ByteSlicePayloadConverter) Encoding 

func (c *ByteSlicePayloadConverter) Encoding() string

Encoding returns MetadataEncodingBinary.

func (*ByteSlicePayloadConverter) FromPayload 

func (c *ByteSlicePayloadConverter) FromPayload(payload *commonpb.Payload, valuePtr interface{}) error

FromPayload converts single []byte value from payload.

func (*ByteSlicePayloadConverter) ToPayload 

func (c *ByteSlicePayloadConverter) ToPayload(value interface{}) (*commonpb.Payload, error)

ToPayload converts single []byte value to payload.

func (*ByteSlicePayloadConverter) ToString 

func (c *ByteSlicePayloadConverter) ToString(payload *commonpb.Payload) string

ToString converts payload object into human readable string.

type CodecDataConverter added in v1.14.0 

type CodecDataConverter struct {
	// contains filtered or unexported fields
}

CodecDataConverter is a DataConverter that wraps an underlying data converter and supports chained encoding of just the payload without regard for serialization to/from actual types.

Example (Compression) 
package main

import (
	"fmt"
	"strings"

	"go.temporal.io/sdk/converter"
)

func main() {
	defaultConv := converter.GetDefaultDataConverter()
	// Create Zlib compression converter
	zlibConv := converter.NewCodecDataConverter(
		defaultConv,
		converter.NewZlibCodec(converter.ZlibCodecOptions{}),
	)

	// Create payloads with both
	bigString := strings.Repeat("aabbcc", 200)
	uncompPayload, _ := defaultConv.ToPayload(bigString)
	compPayload, _ := zlibConv.ToPayload(bigString)

	// The zlib payload is smaller
	fmt.Printf("Uncompressed payload size: %v (encoding: %s)\n",
		len(uncompPayload.Data), uncompPayload.Metadata[converter.MetadataEncoding])
	fmt.Printf("Compressed payload size: %v (encoding: %s)\n",
		len(compPayload.Data), compPayload.Metadata[converter.MetadataEncoding])

	// Convert from payload and confirm the same string. This uses the same
	// compression converter because the converter does not do anything to
	// payloads it didn't previously convert.
	var uncompValue, compValue string
	_ = zlibConv.FromPayload(uncompPayload, &uncompValue)
	_ = zlibConv.FromPayload(compPayload, &compValue)
	fmt.Printf("Uncompressed payload back to original? %v\n", uncompValue == bigString)
	fmt.Printf("Compressed payload back to original? %v\n", compValue == bigString)

}

Output:

Uncompressed payload size: 1202 (encoding: json/plain)
Compressed payload size: 57 (encoding: binary/zlib)
Uncompressed payload back to original? true
Compressed payload back to original? true

func (*CodecDataConverter) FromPayload added in v1.14.0 

func (e *CodecDataConverter) FromPayload(payload *commonpb.Payload, valuePtr interface{}) error

FromPayload implements DataConverter.FromPayload performing decoding on the given payload before sending to the parent FromPayload.

func (*CodecDataConverter) FromPayloads added in v1.14.0 

func (e *CodecDataConverter) FromPayloads(payloads *commonpb.Payloads, valuePtrs ...interface{}) error

FromPayloads implements DataConverter.FromPayloads performing decoding on the given payloads before sending to the parent FromPayloads.

func (*CodecDataConverter) ToPayload added in v1.14.0 

func (e *CodecDataConverter) ToPayload(value interface{}) (*commonpb.Payload, error)

ToPayload implements DataConverter.ToPayload performing encoding on the result of the parent's ToPayload call.

func (*CodecDataConverter) ToPayloads added in v1.14.0 

func (e *CodecDataConverter) ToPayloads(value ...interface{}) (*commonpb.Payloads, error)

ToPayloads implements DataConverter.ToPayloads performing encoding on the result of the parent's ToPayloads call.

func (*CodecDataConverter) ToString added in v1.14.0 

func (e *CodecDataConverter) ToString(payload *commonpb.Payload) string

ToString implements DataConverter.ToString performing decoding on the given payload before sending to the parent ToString.

func (*CodecDataConverter) ToStrings added in v1.14.0 

func (e *CodecDataConverter) ToStrings(payloads *commonpb.Payloads) []string

ToStrings implements DataConverter.ToStrings using ToString for each value.

type CompositeDataConverter 

type CompositeDataConverter struct {
	// contains filtered or unexported fields
}

CompositeDataConverter applies PayloadConverters in specified order.

func (*CompositeDataConverter) FromPayload 

func (dc *CompositeDataConverter) FromPayload(payload *commonpb.Payload, valuePtr interface{}) error

FromPayload converts single value from payload.

func (*CompositeDataConverter) FromPayloads 

func (dc *CompositeDataConverter) FromPayloads(payloads *commonpb.Payloads, valuePtrs ...interface{}) error

FromPayloads converts to a list of values of different types.

func (*CompositeDataConverter) ToPayload 

func (dc *CompositeDataConverter) ToPayload(value interface{}) (*commonpb.Payload, error)

ToPayload converts single value to payload.

func (*CompositeDataConverter) ToPayloads 

func (dc *CompositeDataConverter) ToPayloads(values ...interface{}) (*commonpb.Payloads, error)

ToPayloads converts a list of values.

func (*CompositeDataConverter) ToString 

func (dc *CompositeDataConverter) ToString(payload *commonpb.Payload) string

ToString converts payload object into human readable string.

func (*CompositeDataConverter) ToStrings 

func (dc *CompositeDataConverter) ToStrings(payloads *commonpb.Payloads) []string

ToStrings converts payloads object into human readable strings.

type DataConverter 

type DataConverter interface {
	// ToPayload converts single value to payload.
	ToPayload(value interface{}) (*commonpb.Payload, error)
	// FromPayload converts single value from payload.
	//
	// Note, values should not be reused for extraction here because merging on
	// top of existing values may result in unexpected behavior similar to
	// json.Unmarshal.
	FromPayload(payload *commonpb.Payload, valuePtr interface{}) error

	// ToPayloads converts a list of values.
	ToPayloads(value ...interface{}) (*commonpb.Payloads, error)
	// FromPayloads converts to a list of values of different types.
	// Useful for deserializing arguments of function invocations.
	//
	// Note, values should not be reused for extraction here because merging on
	// top of existing values may result in unexpected behavior similar to
	// json.Unmarshal.
	FromPayloads(payloads *commonpb.Payloads, valuePtrs ...interface{}) error

	// ToString converts payload object into human readable string.
	ToString(input *commonpb.Payload) string
	// ToStrings converts payloads object into human readable strings.
	ToStrings(input *commonpb.Payloads) []string
}

DataConverter is used by the framework to serialize/deserialize input and output of activity/workflow that need to be sent over the wire. To encode/decode workflow arguments, set DataConverter in client, through client.Options. To override DataConverter for specific activity or child workflow use workflow.WithDataConverter to create new Context, and pass that context to ExecuteActivity/ExecuteChildWorkflow calls. Temporal support using different DataConverters for different activity/childWorkflow in same workflow. For advanced data converters that may exceed the deadlock detection timeout for a workflow, such as ones making remote calls, use workflow.DataConverterWithoutDeadlockDetection.

func GetDefaultDataConverter 

func GetDefaultDataConverter() DataConverter

GetDefaultDataConverter returns default data converter used by Temporal worker.

func NewCodecDataConverter added in v1.14.0 

func NewCodecDataConverter(parent DataConverter, codecs ...PayloadCodec) DataConverter

NewCodecDataConverter wraps the given parent DataConverter and performs encoding/decoding on the payload via the given codecs. When encoding for ToPayload(s), the codecs are applied last to first meaning the earlier encoders wrap the later ones. When decoding for FromPayload(s) and ToString(s), the decoders are applied first to last to reverse the effect.

func NewCompositeDataConverter 

func NewCompositeDataConverter(payloadConverters ...PayloadConverter) DataConverter

NewCompositeDataConverter creates a new instance of CompositeDataConverter from an ordered list of PayloadConverters. Order is important here because during serialization the DataConverter will try the PayloadConverters in that order until a PayloadConverter returns non nil payload. The last PayloadConverter should always serialize the value (JSONPayloadConverter is a good candidate for it).

func NewRemoteDataConverter added in v1.14.0 

func NewRemoteDataConverter(parent DataConverter, options RemoteDataConverterOptions) DataConverter

NewRemoteDataConverter wraps the given parent DataConverter and performs encoding/decoding on the payload via the remote endpoint.

type EncodedValue 

type EncodedValue interface {
	// HasValue return whether there is value encoded.
	HasValue() bool
	// Get extract the encoded value into strong typed value pointer.
	//
	// Note, values should not be reused for extraction here because merging on
	// top of existing values may result in unexpected behavior similar to
	// json.Unmarshal.
	Get(valuePtr interface{}) error
}

EncodedValue is used to encapsulate/extract encoded value from workflow/activity.

type EncodedValues 

type EncodedValues interface {
	// HasValues return whether there are values encoded.
	HasValues() bool
	// Get extract the encoded values into strong typed value pointers.
	//
	// Note, values should not be reused for extraction here because merging on
	// top of existing values may result in unexpected behavior similar to
	// json.Unmarshal.
	Get(valuePtr ...interface{}) error
}

EncodedValues is used to encapsulate/extract encoded one or more values from workflow/activity.

type FailureConverter added in v1.18.0 

type FailureConverter interface {
	// ErrorToFailure converts a error to a Failure proto message.
	ErrorToFailure(err error) *failurepb.Failure

	// FailureToError converts a Failure proto message to a Go Error.
	FailureToError(failure *failurepb.Failure) error
}

FailureConverter is used by the sdk to serialize/deserialize errors that need to be sent over the wire. To use a custom FailureConverter, set FailureConverter in client, through client.Options.

type JSONPayloadConverter 

type JSONPayloadConverter struct {
}

JSONPayloadConverter converts to/from JSON.

func NewJSONPayloadConverter 

func NewJSONPayloadConverter() *JSONPayloadConverter

NewJSONPayloadConverter creates a new instance of JSONPayloadConverter.

func (*JSONPayloadConverter) Encoding 

func (c *JSONPayloadConverter) Encoding() string

Encoding returns MetadataEncodingJSON.

func (*JSONPayloadConverter) FromPayload 

func (c *JSONPayloadConverter) FromPayload(payload *commonpb.Payload, valuePtr interface{}) error

FromPayload converts a single payload to a value.

func (*JSONPayloadConverter) ToPayload 

func (c *JSONPayloadConverter) ToPayload(value interface{}) (*commonpb.Payload, error)

ToPayload converts a single value to a payload.

func (*JSONPayloadConverter) ToString 

func (c *JSONPayloadConverter) ToString(payload *commonpb.Payload) string

ToString converts a payload object into a human-readable string.

type NewFailureGRPCClientInterceptorOptions added in v1.20.0 

type NewFailureGRPCClientInterceptorOptions struct {
	// DataConverter is optional. If not set the SDK's dataconverter will be used.
	DataConverter DataConverter
	// Whether to Encode attributes. The current implementation requires this be true.
	EncodeCommonAttributes bool
}

NewFailureGRPCClientInterceptorOptions holds interceptor options.

type NilPayloadConverter 

type NilPayloadConverter struct {
}

NilPayloadConverter doesn't set Data field in payload.

func NewNilPayloadConverter 

func NewNilPayloadConverter() *NilPayloadConverter

NewNilPayloadConverter creates new instance of NilPayloadConverter.

func (*NilPayloadConverter) Encoding 

func (c *NilPayloadConverter) Encoding() string

Encoding returns MetadataEncodingNil.

func (*NilPayloadConverter) FromPayload 

func (c *NilPayloadConverter) FromPayload(_ *commonpb.Payload, valuePtr interface{}) error

FromPayload converts single nil value from payload.

func (*NilPayloadConverter) ToPayload 

func (c *NilPayloadConverter) ToPayload(value interface{}) (*commonpb.Payload, error)

ToPayload converts single nil value to payload.

func (*NilPayloadConverter) ToString 

func (c *NilPayloadConverter) ToString(*commonpb.Payload) string

ToString converts payload object into human readable string.

type PayloadCodec added in v1.14.0 

type PayloadCodec interface {
	// Encode optionally encodes the given payloads which are guaranteed to never
	// be nil. The parameters must not be mutated.
	Encode([]*commonpb.Payload) ([]*commonpb.Payload, error)

	// Decode optionally decodes the given payloads which are guaranteed to never
	// be nil. The parameters must not be mutated.
	//
	// For compatibility reasons, implementers should take care not to decode
	// payloads that were not previously encoded.
	Decode([]*commonpb.Payload) ([]*commonpb.Payload, error)
}

PayloadCodec is an codec that encodes or decodes the given payloads.

For example, NewZlibCodec returns a PayloadCodec that can be used for compression. These can be used (and even chained) in NewCodecDataConverter.

func NewRemotePayloadCodec added in v1.26.0 

func NewRemotePayloadCodec(options RemotePayloadCodecOptions) PayloadCodec

NewRemotePayloadCodec creates a PayloadCodec using the remote endpoint configured by RemotePayloadCodecOptions.

func NewZlibCodec added in v1.14.0 

func NewZlibCodec(options ZlibCodecOptions) PayloadCodec

NewZlibCodec creates a PayloadCodec for use in NewCodecDataConverter to support zlib payload compression.

While this serves as a reasonable example of a compression encoder, callers may prefer alternative compression algorithms for lots of small payloads.

type PayloadCodecGRPCClientInterceptorOptions added in v1.14.0 

type PayloadCodecGRPCClientInterceptorOptions struct {
	Codecs []PayloadCodec
}

PayloadCodecGRPCClientInterceptorOptions holds interceptor options. Currently this is just the list of codecs to use.

type PayloadConverter 

type PayloadConverter interface {
	// ToPayload converts a single value to payload. It should return nil if the
	// PayloadConverter can not convert the passed value (i.e. type is unknown).
	ToPayload(value interface{}) (*commonpb.Payload, error)
	// FromPayload converts single value from payload. valuePtr should be a
	// reference to a variable of a type corresponding to the payload
	// encoding. Otherwise it should return error.
	FromPayload(payload *commonpb.Payload, valuePtr interface{}) error
	// ToString converts payload object into human readable string.
	ToString(*commonpb.Payload) string

	// Encoding returns encoding supported by PayloadConverter.
	Encoding() string
}

PayloadConverter is an interface to convert a single payload.

type ProtoJSONPayloadConverter 

type ProtoJSONPayloadConverter struct {
	// contains filtered or unexported fields
}

ProtoJSONPayloadConverter converts proto objects to/from JSON.

func NewProtoJSONPayloadConverter 

func NewProtoJSONPayloadConverter() *ProtoJSONPayloadConverter

NewProtoJSONPayloadConverter creates new instance of `ProtoJSONPayloadConverter`.

func NewProtoJSONPayloadConverterWithOptions added in v1.13.0 

func NewProtoJSONPayloadConverterWithOptions(options ProtoJSONPayloadConverterOptions) *ProtoJSONPayloadConverter

NewProtoJSONPayloadConverterWithOptions creates new instance of `ProtoJSONPayloadConverter` with the provided options.

func (*ProtoJSONPayloadConverter) Encoding 

func (c *ProtoJSONPayloadConverter) Encoding() string

Encoding returns MetadataEncodingProtoJSON.

func (*ProtoJSONPayloadConverter) ExcludeProtobufMessageTypes added in v1.13.0 

func (c *ProtoJSONPayloadConverter) ExcludeProtobufMessageTypes() bool

func (*ProtoJSONPayloadConverter) FromPayload 

func (c *ProtoJSONPayloadConverter) FromPayload(payload *commonpb.Payload, valuePtr interface{}) error

FromPayload converts single proto value from payload.

func (*ProtoJSONPayloadConverter) ToPayload 

func (c *ProtoJSONPayloadConverter) ToPayload(value interface{}) (*commonpb.Payload, error)

ToPayload converts single proto value to payload.

func (*ProtoJSONPayloadConverter) ToString 

func (c *ProtoJSONPayloadConverter) ToString(payload *commonpb.Payload) string

ToString converts payload object into human readable string.

type ProtoJSONPayloadConverterOptions added in v1.13.0 

type ProtoJSONPayloadConverterOptions struct {
	// ExcludeProtobufMessageTypes prevents the message type (`my.package.MyMessage`)
	// from being included in the Payload.
	ExcludeProtobufMessageTypes bool

	// AllowUnknownFields will ignore unknown fields when unmarshalling, as opposed to returning an error
	AllowUnknownFields bool

	// UseProtoNames uses proto field name instead of lowerCamelCase name in JSON
	// field names.
	UseProtoNames bool

	// UseEnumNumbers emits enum values as numbers.
	UseEnumNumbers bool

	// EmitUnpopulated specifies whether to emit unpopulated fields.
	EmitUnpopulated bool
}

ProtoJSONPayloadConverterOptions represents options for `NewProtoJSONPayloadConverterWithOptions`.

type ProtoPayloadConverter 

type ProtoPayloadConverter struct {
	// contains filtered or unexported fields
}

ProtoPayloadConverter converts proto objects to protobuf binary format.

func NewProtoPayloadConverter 

func NewProtoPayloadConverter() *ProtoPayloadConverter

NewProtoPayloadConverter creates new instance of `ProtoPayloadConverter“.

func NewProtoPayloadConverterWithOptions added in v1.13.0 

func NewProtoPayloadConverterWithOptions(options ProtoPayloadConverterOptions) *ProtoPayloadConverter

NewProtoPayloadConverterWithOptions creates new instance of `ProtoPayloadConverter` with the provided options.

func (*ProtoPayloadConverter) Encoding 

func (c *ProtoPayloadConverter) Encoding() string

Encoding returns MetadataEncodingProto.

func (*ProtoPayloadConverter) ExcludeProtobufMessageTypes added in v1.13.0 

func (c *ProtoPayloadConverter) ExcludeProtobufMessageTypes() bool

func (*ProtoPayloadConverter) FromPayload 

func (c *ProtoPayloadConverter) FromPayload(payload *commonpb.Payload, valuePtr interface{}) error

FromPayload converts single proto value from payload.

func (*ProtoPayloadConverter) ToPayload 

func (c *ProtoPayloadConverter) ToPayload(value interface{}) (*commonpb.Payload, error)

ToPayload converts single proto value to payload.

func (*ProtoPayloadConverter) ToString 

func (c *ProtoPayloadConverter) ToString(payload *commonpb.Payload) string

ToString converts payload object into human readable string.

type ProtoPayloadConverterOptions added in v1.13.0 

type ProtoPayloadConverterOptions struct {
	// ExcludeProtobufMessageTypes prevents the message type (`my.package.MyMessage`)
	// from being included in the Payload.
	ExcludeProtobufMessageTypes bool
}

ProtoPayloadConverterOptions represents options for `NewProtoPayloadConverterWithOptions`.

type RemoteDataConverterOptions added in v1.14.0 

type RemoteDataConverterOptions struct {
	Endpoint      string
	ModifyRequest func(*http.Request) error
	Client        http.Client
}

RemoteDataConverterOptions are options for NewRemoteDataConverter.

type RemotePayloadCodecOptions added in v1.26.0 

type RemotePayloadCodecOptions struct {
	Endpoint      string
	ModifyRequest func(*http.Request) error
	Client        http.Client
}

RemotePayloadCodecOptions are options for RemotePayloadCodec. Client is optional.

type ZlibCodecOptions added in v1.14.0 

type ZlibCodecOptions struct {
	// If true, the zlib codec will encode the contents even if there is no size
	// benefit. Otherwise, the zlib codec will only use the encoded value if it
	// is smaller.
	AlwaysEncode bool
}

ZlibCodecOptions are options for NewZlibCodec. All fields are optional.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.