temporal_sdk_grpc (temporal_sdk v0.1.15)
View SourcegRPC request module.
gRPC request module provides unary gRPC request functionality.
Module is used by the temporal_sdk_client module.
Functions provided by the temporal_sdk_api module should be used for low-level gRPC request
handling; see temporal_sdk_api:request/3 and temporal_sdk_api:request/5.
gRPC request life cycle
flowchart LR
TS@{ shape: processes, label: "Temporal Service <br> Temporal Server(s)"}
style TS stroke-dasharray: 3 3
subgraph REQUEST
direction TB
rq1[gRPC request] --> rq2[intercept request]
rq2 --> rq3[convert request payloads]
rq3 --> rq4[encode protobuf]
rq4 --> rq5[compress]
rq5 --> rq6[add headers]
rq6 --> rq7[check message size]
end
REQUEST -.-> TS
subgraph RESPONSE
direction TB
rp1[gRPC response] --> rp2[decompress]
rp2 --> rp3[decode protobuf]
rp3 --> rp4[convert response payloads]
rp4 --> rp5[intercept response]
end
TS -.-> RESPONSESummary
Types
gRPC HTTP/2 adapter configuration.
gRPC service server/cluster name.
gRPC Protocol Buffers (protobuf) codec.
gRPC compressor configuration.
Payload converter configuration.
Payload converter codec configuration.
Payload converter codecs configuration.
Payload converter gRPC message-specific codecs configuration.
Payload converter default codecs configuration.
gRPC request HTTP/2 headers.
gRPC interceptor configuration.
gRPC service message type specification.
gRPC service message name.
gRPC request options.
gRPC service info.
Result of a gRPC request.
Result of a failed gRPC request.
Result of a successful gRPC request.
gRPC request retry policy.
Types
gRPC HTTP/2 adapter configuration.
Adapter configuration is expressed as a tuple.
The first tuple element is an HTTP/2 adapter module that implements the temporal_sdk_grpc_adapter
behaviour.
The second tuple element is an adapter configuration that is specific to that adapter.
SDK provides two HTTP/2 adapter implementations, both based on the gun library:
temporal_sdk_grpc_adapter_gun(default),temporal_sdk_grpc_adapter_gun_pool.
-type cluster_name() :: atom().
gRPC service server/cluster name.
gRPC Protocol Buffers (protobuf) codec.
Codec configuration is expressed as a tuple.
First tuple element is a codec module implementing temporal_sdk_grpc_codec behaviour.
Second and third tuple elements are the encode and decode operation options respectively.
SDK provides two built-in protobuf codecs:
temporal_sdk_codec_binaries(default),temporal_sdk_codec_strings.
gRPC compressor configuration.
Compressor configuration is expressed as a tuple.
First tuple element is a compressor module implementing temporal_sdk_grpc_compressor behaviour.
Second and third tuple elements are the compress and decompress operation options respectively.
SDK provides two built-in compressors:
temporal_sdk_grpc_compressor_gzip,temporal_sdk_grpc_compressor_identity(default).
-type converter() :: {ConverterModule :: module(), ConverterCodecs :: converter_codecs()}.
Payload converter configuration.
Payload converter configuration is defined as a tuple.
Tuple first element is a payload converter module implementing temporal_sdk_grpc_converter behaviour.
Tuple second element is a payload converter codecs configuration, see converter_codecs/0.
SDK provides a built-in Temporal payload converter: temporal_sdk_proto_converter.
See GitHub: SDK samples repository "Payload Converter" sample for payload converter codec example:
- Elixir: lib/payload_converter,
- Erlang: src/payload_converter.
-type converter_codec() :: Module :: module() | {Module :: module(), EncodeOpts :: term(), DecodeOpts :: term()}.
Payload converter codec configuration.
Payload converter codec configuration can be expressed in two alternative ways:
- as a codec module implementing the
temporal_sdk_codec_payloadbehaviour, - as a tuple containing a codec module implementing the
temporal_sdk_codec_payloadbehaviour, and encode and decode operation options.
SDK provides following built-in payload converter codecs:
temporal_sdk_codec_payload_binary,temporal_sdk_codec_payload_erl,temporal_sdk_codec_payload_json,temporal_sdk_codec_payload_text.
-type converter_codecs() :: {ConverterDefaultCodecs :: converter_default_codecs(), ConverterCustomCodecs :: converter_custom_codecs()} | (ConverterDefaultCodecs :: converter_default_codecs()).
Payload converter codecs configuration.
Payload converter codecs configuration can be expressed in two alternative ways:
- as a list of default codecs that will be applied to all gRPC messages,
- as a tuple containing two elements: a list of default codecs and a list of gRPC message-specific codecs.
Codecs are applied in the order specified in the configuration list.
-type converter_custom_codecs() :: [{[converter_codec()], [MsgName :: atom() | {MsgName :: atom(), MsgKey :: atom()}]}].
Payload converter gRPC message-specific codecs configuration.
-type converter_default_codecs() :: [converter_codec()].
Payload converter default codecs configuration.
-type headers() :: [{nonempty_binary() | string() | atom(), iodata()}] | #{nonempty_binary() | string() | atom() => iodata()}.
gRPC request HTTP/2 headers.
-type interceptor() :: {Module :: module(), HandleRequestOpts :: term(), HandleResponseOpts :: term()}.
gRPC interceptor configuration.
Interceptor configuration is expressed as a tuple.
First tuple element is a interceptor module implementing temporal_sdk_grpc_interceptor behaviour.
Second and third tuple elements are the intercept request and response handler options respectively.
SDK provides one built-in interceptor: temporal_sdk_grpc_interceptor_identity.
-type msg() :: dynamic().
gRPC service message type specification.
-type msg_name() :: term().
gRPC service message name.
-type opts() :: #{converter => converter(), codec => codec(), compressor => compressor(), interceptor => interceptor(), timeout => non_neg_integer(), retry_policy => retry_policy(), headers => headers(), maximum_request_size => pos_integer()}.
gRPC request options.
-type request_info() :: #{type := request | response, content_type := binary(), input := atom(), input_stream := boolean(), output := atom(), output_stream := boolean(), msg_type := binary(), name := atom(), opts := list(), service_fqname := atom()}.
gRPC service info.
-type result() :: result_success() | result_error().
Result of a gRPC request.
-type result_error() :: {error, Reason :: term()}.
Result of a failed gRPC request.
-type result_success() :: {ok, ResponseMsg :: msg()}.
Result of a successful gRPC request.
-type retry_policy() :: disabled | #{initial_interval := pos_integer(), backoff_coefficient := pos_integer(), maximum_interval := pos_integer(), max_attempts := pos_integer(), is_retryable := fun((Result :: result(), RequestInfo :: request_info(), Attempt :: pos_integer()) -> boolean())}.
gRPC request retry policy.
Retry policy is configured as a map with following configuration options:
initial_interval- amount of time that must elapse before the first retry occurs,backoff_coefficient- value dictating how much the retry interval increases,maximum_interval- specifies the maximum interval between retries,max_attempts- specifies the maximum number of execution attempts that can be made in the presence of failures,is_retryable- function evaluating if given request failure is retryable.