converter

package
v1.49.0 Latest Latest
Warning

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

 Go to latest Published: Sep 14, 2026 License: MIT Imports: 20 Imported by: 247

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 GetPayloads added in v1.45.0 

func GetPayloads(encoded any) *commonpb.Payloads

GetPayloads acts as a helper to extract the raw *commonpb.Payloads from an EncodedValue or EncodedValues, if the underlying implementation supports it via the ValuesPayloads interface. If the underlying implementation does not support it, this returns nil.

Exposed as: go.temporal.io/sdk/converter.GetPayloads

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. When combining this with NewFailureGRPCClientInterceptor you should ensure that NewFailureGRPCClientInterceptor is before NewPayloadCodecGRPCClientInterceptor in the chain.

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.

func NewPayloadHTTPHandler added in v1.43.0 

func NewPayloadHTTPHandler(options PayloadHTTPHandlerOptions) (http.Handler, error)

NewPayloadHTTPHandler creates an http.Handler that serves /encode, /decode, and /download routes for remote payload transformations.

NOTE: Experimental

Types

type ActivitySerializationContext added in v1.42.0 

type ActivitySerializationContext struct {
	Namespace string
	// Empty for a standalone activity.
	WorkflowID string
	// Empty for a standalone activity.
	WorkflowType string
	ActivityType string
	TaskQueue    string
	IsLocal      bool
}

ActivitySerializationContext is the serialization context for activity-level payloads. This includes: activity input/result, heartbeat details, and activity failure details.

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 any) error

FromPayload converts single []byte value from payload.

func (*ByteSlicePayloadConverter) ToPayload 

func (c *ByteSlicePayloadConverter) ToPayload(value any) (*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) 
defaultConv := GetDefaultDataConverter()
// Create Zlib compression converter
zlibConv := NewCodecDataConverter(
	defaultConv,
	NewZlibCodec(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[MetadataEncoding])
fmt.Printf("Compressed payload is smaller? %v (encoding: %s)\n",
	len(compPayload.Data) < len(uncompPayload.Data), compPayload.Metadata[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 is smaller? true (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 any) 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 ...any) 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 any) (*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 ...any) (*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.

func (*CodecDataConverter) WithSerializationContext added in v1.42.0 

func (e *CodecDataConverter) WithSerializationContext(ctx SerializationContext) DataConverter

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 any) error

FromPayload converts single value from payload.

func (*CompositeDataConverter) FromPayloads 

func (dc *CompositeDataConverter) FromPayloads(payloads *commonpb.Payloads, valuePtrs ...any) error

FromPayloads converts to a list of values of different types.

func (*CompositeDataConverter) ToPayload 

func (dc *CompositeDataConverter) ToPayload(value any) (*commonpb.Payload, error)

ToPayload converts single value to payload.

func (*CompositeDataConverter) ToPayloads 

func (dc *CompositeDataConverter) ToPayloads(values ...any) (*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.
	//
	// Note: When value is of RawValue type, encoding should occur, but data conversion must be skipped.
	ToPayload(value any) (*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.
	//
	// Note: When valuePtr is of RawValue type, decryption should occur but data conversion must be skipped.
	FromPayload(payload *commonpb.Payload, valuePtr any) error

	// ToPayloads converts a list of values.
	ToPayloads(value ...any) (*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 ...any) 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.

func WithDataConverterSerializationContext added in v1.42.0 

func WithDataConverterSerializationContext(dc DataConverter, ctx SerializationContext) DataConverter

WithDataConverterSerializationContext returns a DataConverter that is aware of the given serialization context. If the DataConverter implements DataConverterWithSerializationContext, it delegates to that implementation; otherwise it returns the original DataConverter unchanged.

type DataConverterWithSerializationContext added in v1.42.0 

type DataConverterWithSerializationContext interface {
	WithSerializationContext(SerializationContext) DataConverter
}

DataConverterWithSerializationContext is an optional interface that DataConverter implementations can implement to receive serialization context.

When implemented, the SDK calls WithSerializationContext before serializing/deserializing payloads. The returned DataConverter should use the context to vary its behavior (e.g. using workflow ID as associated data for encryption).

Implementations must work correctly without context — the SDK and user code may use the DataConverter directly without calling WithSerializationContext first.

This method should be cheap and fast. The SDK does not cache returned instances and may call this method frequently. Avoid recreating expensive objects on every call.

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 any) 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 ...any) error
}

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

type ExternalStorage added in v1.42.0 

type ExternalStorage = extstore.ExternalStorage

ExternalStorage configures external payload storage for a Temporal client or worker. When set, the SDK intercepts payloads on the way to and from the Temporal server: payloads that exceed PayloadSizeThreshold are offloaded to an external store by the configured driver(s), and storage references are substituted in the history event. The references are resolved back to the original payloads before they reach the data converter or application code.

NOTE: Experimental

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.

func WithFailureConverterSerializationContext added in v1.42.0 

func WithFailureConverterSerializationContext(fc FailureConverter, ctx SerializationContext) FailureConverter

WithFailureConverterSerializationContext returns a FailureConverter that is aware of the given serialization context. If the FailureConverter implements FailureConverterWithSerializationContext, it delegates to that implementation; otherwise it returns the original FailureConverter unchanged.

type FailureConverterWithSerializationContext added in v1.42.0 

type FailureConverterWithSerializationContext interface {
	WithSerializationContext(SerializationContext) FailureConverter
}

FailureConverterWithSerializationContext is an optional interface that FailureConverter implementations can implement to receive serialization context.

When implemented, the SDK calls WithSerializationContext before converting errors to/from failures. The returned FailureConverter should use the context to vary its behavior (e.g. encrypting failure details using a workflow-ID-derived key).

Implementations must work correctly without context — the SDK and user code may use the FailureConverter directly without calling WithSerializationContext first.

This method should be cheap and fast. The SDK does not cache returned instances and may call this method frequently. Avoid recreating expensive objects on every call.

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 any) error

FromPayload converts a single payload to a value.

func (*JSONPayloadConverter) ToPayload 

func (c *JSONPayloadConverter) ToPayload(value any) (*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 NexusSerializationContext added in v1.49.0 

type NexusSerializationContext struct {
	// Endpoint is the Nexus endpoint name.
	Endpoint string
	// Service is the Nexus service name.
	Service string
	// Operation is the resolved Nexus operation name.
	Operation string
}

NexusSerializationContext is used when serializing Nexus operation payloads. Callers receive it when encoding inputs and decoding results or failures. Handlers receive it when decoding inputs, encoding synchronous results, and encoding failures produced while handling a Nexus task.

Operation is the resolved operation name. The context is not propagated to the eventual result of an asynchronous operation. Standalone operation handles use the context of their start request, including when an existing operation is returned, while handles created without starting an operation do not receive it.

For failures, callers receive this context in FailureConverter.FailureToError, while handlers receive it in FailureConverter.ErrorToFailure. Implementations must not assume symmetric failure conversion. Context-dependent encodings should be self-describing and support legacy payloads without context.

NOTE: Experimental

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 any) error

FromPayload converts single nil value from payload.

func (*NilPayloadConverter) ToPayload 

func (c *NilPayloadConverter) ToPayload(value any) (*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.

PayloadCodec methods may run while processing a Workflow Task or in a Client or Activity context. When called during Workflow Task processing, returning an error may fail the Workflow Execution, depending on the operation. A panic is handled according to the Worker's WorkflowPanicPolicy. With the default BlockWorkflow policy, a panic fails the current Workflow Task so that the Temporal Service can retry it. With the FailWorkflow policy, a panic instead fails the Workflow Execution.

Codec implementations should handle transient failures locally when possible. Panicking outside Workflow Task processing does not request a Workflow Task retry.

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 PayloadCodecWithSerializationContext added in v1.42.0 

type PayloadCodecWithSerializationContext interface {
	WithSerializationContext(SerializationContext) PayloadCodec
}

PayloadCodecWithSerializationContext is an optional interface that PayloadCodec implementations can implement to receive serialization context.

When implemented, the SDK calls WithSerializationContext before encoding/decoding payloads. The returned PayloadCodec should use the context to vary its behavior (e.g. using workflow ID as associated data for encoding).

Implementations must work correctly without context — the SDK and user code may use the PayloadCodec directly without calling WithSerializationContext first.

This method should be cheap and fast. The SDK does not cache returned instances and may call this method frequently. Avoid recreating expensive objects on every call.

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 any) (*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 any) 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 PayloadHTTPHandlerOptions added in v1.43.0 

type PayloadHTTPHandlerOptions struct {
	// PostStorageCodecs are codecs applied after external storage from the
	// perspective of payloads going through a encoding transformation. These are
	// typically the codecs that would be configured in the proxy's codec chain.
	// When encoding, the codecs are applied last to first meaning the earlier
	// codecs wrap the later ones. When decoding, the codecs are applied first
	// to last to reverse the effect.
	//
	// NOTE: Experimental.
	PostStorageCodecs []PayloadCodec

	// PreStorageCodecs are codecs that are applied before external storage,
	// from the perspective of payloads going through an encoding transformation.
	// These are typically the codecs that would be configured in the DataConverter
	// codec chain on a Temporal client. When encoding, the codecs are applied last
	// to first meaning the earlier codecs wrap the later ones. When decoding, the
	// codecs are applied first to last to reverse the effect.
	//
	// NOTE: Experimental.
	PreStorageCodecs []PayloadCodec

	// ExternalStorage configures external payload storage, allowing payloads
	// to be stored and retrieved from external sources if they meet the size
	// threshold and driver selection criteria.
	//
	// NOTE: Experimental.
	ExternalStorage ExternalStorage
}

PayloadHTTPHandlerOptions configures a NewPayloadHTTPHandler.

NOTE: Experimental

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 any) error

FromPayload converts single proto value from payload.

func (*ProtoJSONPayloadConverter) ToPayload 

func (c *ProtoJSONPayloadConverter) ToPayload(value any) (*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

	// LegacyTemporalProtoCompat will allow enums serialized as SCREAMING_SNAKE_CASE.
	// Useful for backwards compatibility when migrating a proto message from gogoproto to standard protobuf.
	LegacyTemporalProtoCompat 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 any) error

FromPayload converts single proto value from payload.

func (*ProtoPayloadConverter) ToPayload 

func (c *ProtoPayloadConverter) ToPayload(value any) (*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 RawValue added in v1.34.0 

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

RawValue is a representation of an unconverted, raw payload.

This type can be used as a parameter or return type in workflows and activities to pass through a raw payload. Encoding/decoding of the payload is still done by the system. A RawValue enabled payload converter is required for this.

func NewRawValue added in v1.34.0 

func NewRawValue(payload *commonpb.Payload) RawValue

NewRawValue creates a new RawValue instance.

func (RawValue) MarshalJSON added in v1.34.0 

func (v RawValue) MarshalJSON() ([]byte, error)

func (RawValue) Payload added in v1.34.0 

func (v RawValue) Payload() *commonpb.Payload

func (*RawValue) UnmarshalJSON added in v1.34.0 

func (v *RawValue) UnmarshalJSON(b []byte) error

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 SerializationContext added in v1.42.0 

type SerializationContext interface {
	// contains filtered or unexported methods
}

SerializationContext provides metadata about where serialization is occurring, with the concrete type depending on the context:

type StorageDriver added in v1.42.0 

type StorageDriver = extstore.StorageDriver

StorageDriver is the interface that must be implemented to back external payload storage. When a payload exceeds the configured size threshold the SDK calls Store instead of embedding it in the Temporal history event. On the read path the SDK calls Retrieve using the claim that was persisted with the event, transparently restoring the original payload before it is decoded by the data converter.

NOTE: Experimental

type StorageDriverActivityInfo added in v1.42.0 

type StorageDriverActivityInfo = extstore.StorageDriverActivityInfo

StorageDriverActivityInfo carries activity identity for a storage operation. This is only used for standalone (non-workflow-bound) activities; activities started by a workflow use StorageDriverWorkflowInfo as the target.

NOTE: Experimental

type StorageDriverClaim added in v1.42.0 

type StorageDriverClaim = extstore.StorageDriverClaim

StorageDriverClaim is an opaque token returned by StorageDriver.Store that identifies where a payload was stored. The SDK serializes it alongside the payload metadata so that StorageDriver.Retrieve can locate the data later. Drivers encode their own addressing information (e.g. a bucket name and object key) into the ClaimData map.

NOTE: Experimental

type StorageDriverRetrieveContext added in v1.42.0 

type StorageDriverRetrieveContext = extstore.StorageDriverRetrieveContext

StorageDriverRetrieveContext carries context passed to StorageDriver.Retrieve operations.

NOTE: Experimental

type StorageDriverSelectContext added in v1.49.0 

type StorageDriverSelectContext = extstore.StorageDriverSelectContext

StorageDriverSelectContext carries context passed to StorageDriverSelector.SelectDriver operations.

NOTE: Experimental

type StorageDriverSelector added in v1.42.0 

type StorageDriverSelector = extstore.StorageDriverSelector

StorageDriverSelector chooses which StorageDriver should store a given payload, or returns nil to leave the payload inline (not stored externally). Use this when different payloads should be routed to different backends. For example, routing large binary blobs to object storage while keeping small JSON payloads inline. If no selector is set, the first driver in ExternalStorage.Drivers is used for every payload that exceeds the size threshold.

NOTE: Experimental

type StorageDriverStoreContext added in v1.42.0 

type StorageDriverStoreContext = extstore.StorageDriverStoreContext

StorageDriverStoreContext carries context passed to StorageDriver.Store operations.

NOTE: Experimental

type StorageDriverTargetInfo added in v1.42.0 

type StorageDriverTargetInfo = extstore.StorageDriverTargetInfo

StorageDriverTargetInfo identifies the workflow or activity on whose behalf a payload is being stored. Use a type switch on StorageDriverWorkflowInfo and StorageDriverActivityInfo to access the concrete values.

NOTE: Experimental

type StorageDriverWorkflowInfo added in v1.42.0 

type StorageDriverWorkflowInfo = extstore.StorageDriverWorkflowInfo

StorageDriverWorkflowInfo carries workflow identity for a storage operation.

NOTE: Experimental

type ValuesPayloads added in v1.45.0 

type ValuesPayloads interface {
	// Payloads gets the underlying commonpb.Payloads without decoding
	Payloads() *commonpb.Payloads
}

ValuesPayloads is an optional interface that EncodedValue and EncodedValues may implement to expose the underlying commonpb.Payloads without decoding.

type WorkflowSerializationContext added in v1.42.0 

type WorkflowSerializationContext struct {
	Namespace  string
	WorkflowID string
}

WorkflowSerializationContext is the serialization context for workflow-level payloads. This includes: workflow input/result, child workflow input/result, signal input, query input/result, update input/result, memo, continue-as-new args, and external signal payloads.

For child workflows, WorkflowID is the child's ID, not the parent's. For external signals, WorkflowID is the target workflow's ID.

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.