architecture/client

31 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Temporal Client library and gRPC connection

A Temporal Client is a library object from a Temporal SDK that application code uses to talk to the Temporal Server's Frontend. It opens a network connection using gRPC to the Server and sends requests like 'start this Workflow with these inputs,' 'cancel this Workflow,' 'send this Signal to a running Workflow,' 'run this Query on a Workflow,' or 'get the result of this Workflow.'

Client does not run Workflow or Activity code

The Client does not run Workflow or Activity code; it only sends and receives control requests. This gives existing services, CLIs, or UIs a simple and consistent way to interact with Temporal without knowing anything about how Tasks, Task Queues, or Event histories are implemented inside the Server.

Data security with Data Converter

The Data Converter ensures that all sensitive data exists in its original format only on hosts that you control. Data is encoded before being sent to the Temporal Service, keeping sensitive information secure throughout transmission and storage.

Data Converter encoding is automatic

Data encoding is performed automatically using the default converter provided by Temporal or your custom Data Converter when passing input to a Temporal Service. Plain text input is usually serialized into a JSON object.

Data Converter decoding is asymmetric

Data decoding may be performed by your application logic during Workflows or Activities as necessary, but decoded Workflow results are never persisted back to the Temporal Service. Instead, they are stored encoded on the Temporal Service, and you need to provide an additional parameter when using 'temporal workflow show' or when browsing the Web UI to view output.

Data Converter purpose and role

Data Converters in Temporal are SDK components that handle the serialization and encoding of data entering and exiting a Temporal Service. Workflow inputs and outputs need to be serialized and deserialized so they can be sent as JSON to a Temporal Service. The Data Converter encodes data from your application to a Payload before it is sent to the Temporal Service in the Client call. When the Temporal Server sends the encoded data back to the Worker, the Data Converter decodes it for processing within your application.

Payload definition and structure

A Payload represents binary data such as input and output from Activities and Workflows. Payloads contain metadata that describe their data type or other parameters for use by custom encoders/converters. Each piece of data (like a single argument or return value) is encoded as a Payload, which consists of binary data and key-value metadata.

Custom Payload Converter for different conversion steps

You can create a custom Payload Converter to apply different conversion steps beyond the default Data Converter. Additionally, you can apply custom codecs such as for encryption or compression on your Payloads.

Standalone Nexus Operation definition

A Standalone Nexus Operation is a top-level Nexus Operation Execution started directly by a Client, without using a caller Workflow.

Temporal Client operations: standalone activities and Nexus

A Temporal Client allows you to start and manage Standalone Activities directly without involving a Workflow, and start a Standalone Nexus Operation directly without using a caller Workflow.

Temporal Client definition and purpose

A Temporal Client acts as the bridge for communication between your applications and the Temporal Service. It enables you to start Workflow Executions, send Signals and Queries, and retrieve results.

Temporal Client operations: list and interact with workflows

A Temporal Client allows you to list Workflow Executions, Query a Workflow Execution, and Signal a Workflow Execution.

Temporal Client operations: start and retrieve workflows

A Temporal Client allows you to start a Workflow Execution and get the result of Workflow Execution.

TemporalClient.ConnectAsync method for creating a client

Use TemporalClient.ConnectAsync to create a Temporal Client. Connection options include the Temporal Server address, Namespace, and (optionally) TLS configuration. These options can be provided directly in code, or loaded from environment variables and/or a TOML configuration file using Temporalio.Client.EnvConfig helpers. Environment variables or configuration files are recommended for secure, repeatable configuration.

Temporal Client enables communication with Temporal Service

A Temporal Client enables you to communicate with the Temporal Service and perform actions such as starting Workflow Executions, sending Signals and Queries to Workflow Executions, and getting Workflow results. For Standalone Activities, a Temporal Client can also start and manage Standalone Activities directly, without involving a Workflow.

Temporal Client cannot be initialized inside a Workflow

A Temporal Client cannot be initialized and used inside a Workflow. However, it is acceptable and common to use a Temporal Client inside an Activity to communicate with a Temporal Service.

Default local connection defaults

When running a Temporal Service locally, if you don't specify a host/port, most connections default to 127.0.0.1:7233 and the default Namespace.

TOML configuration file for Temporal Client connection options

You can use a TOML configuration file to set connection options for the Temporal Client. The configuration file lets you configure multiple profiles, each with its own set of connection options. You can use the environment variable TEMPORAL_CONFIG_FILE to specify the location of the TOML file or provide the path to the file directly in code. If you don't provide the configuration file path, the SDK looks for it at the path ~/.config/temporalio/temporal.toml or the equivalent on your OS.

Environment variables override configuration file settings

The connection options set in configuration files have lower precedence than environment variables. If you set the same option in both the configuration file and as an environment variable, the environment variable value overrides the option set in the configuration file.

Temporal Cloud connection requires API key or mTLS

Connection to Temporal Cloud or any secured Temporal Service requires credentials for authentication: either an API key value or mTLS CA certificate and mTLS private key. You must also provide your Namespace and Account ID combination in the format <namespace_id>.<account_id>. The recommended endpoint is the gRPC Namespace endpoint: <namespace>.<account>.tmprl.cloud:7233, which automatically directs traffic to the active region for Namespaces with High Availability.

Environment variables for Temporal Cloud connection

The following environment variables are required to connect to Temporal Cloud: TEMPORAL_NAMESPACE (Namespace and Account ID combination in format <namespace_id>.<account_id>), TEMPORAL_ADDRESS (gRPC endpoint for Temporal Cloud Namespace), TEMPORAL_API_KEY (API key value for API key authentication), TEMPORAL_TLS_CLIENT_CERT_DATA or TEMPORAL_TLS_CLIENT_CERT_PATH (mTLS client certificate data or file path for mTLS authentication), TEMPORAL_TLS_CLIENT_KEY_DATA or TEMPORAL_TLS_CLIENT_KEY_PATH (mTLS client private key data or file path for mTLS authentication).

Updating API key on existing client connection

To update an API key on an existing Temporal Client connection, update the value of ApiKey on the existing client connection: myClient.Connection.ApiKey = myKeyUpdated;

mTLS certificate rotation by connecting new client

Unlike ApiKey, TlsOptions is not mutable on an existing connection. To rotate an mTLS client certificate without restarting your Worker, connect a new client with the new certificate and assign it to the running TemporalWorker's Client property: worker.Client = newClient;. This replaces the connection the Worker uses for subsequent calls to the Temporal Service (Workflow Task completion, Activity Heartbeats, and so on); calls already in flight on the old client are not interrupted.

ClientEnvConfig.LoadClientConnectOptions for loading configuration

Use ClientEnvConfig.LoadClientConnectOptions() to load connection options from environment variables and/or configuration files. This method automatically loads all environment variables and will also load the default profile in the configuration file if defined at the default location (~/.config/temporalio/temporal.toml) or a custom location specified by the TEMPORAL_CONFIG_FILE environment variable. Options set via environment variables take precedence over configuration file settings.

temporal CLI global flags - connection and auth

Global flags for temporal CLI: --address (string, optional, default localhost:7233): Temporal Service gRPC endpoint; --api-key (string, optional): API key for request; --client-authority (string, optional): Temporal gRPC client :authority pseudoheader; --client-connect-timeout (duration, optional): Client connection timeout, 0s means no timeout; --codec-auth (string, optional): Authorization header for Codec Server requests; --codec-endpoint (string, optional): Remote Codec Server endpoint; --codec-header (string[], optional): HTTP headers for codec server requests, KEY=VALUE format; --tls (bool, optional): Enable base TLS encryption, defaults to true if api-key or other TLS options present, use --tls=false to disable; --tls-ca-data (string, optional): Data for server CA certificate, can't use with --tls-ca-path; --tls-ca-path (string, optional): Path to server CA certificate, can't use with --tls-ca-data; --tls-cert-data (string, optional): Data for x509 certificate, can't use with --tls-cert-path; --tls-cert-path (string, optional): Path to x509 certificate, can't use with --tls-cert-data; --tls-disable-host-verification (bool, optional): Disable TLS host-name verification; --tls-key-data (string, optional): Private certificate key data, can't use with --tls-key-path; --tls-key-path (string, optional): Path to x509 private key, can't use with --tls-key-data; --tls-server-name (string, optional): Override target TLS server name.

temporal CLI global flags - configuration and environment

Global flags for temporal CLI configuration: --config-file (string, optional): File path to read TOML config, defaults to $CONFIG_PATH/temporalio/temporal.toml; --disable-config-env (bool, optional): Disable loading environment config from environment variables; --disable-config-file (bool, optional): Disable loading environment config from config file; --env (string, optional, default default): Active environment name (ENV); --env-file (string, optional): Path to environment settings file, defaults to $HOME/.config/temporalio/temporal.yaml; --profile (string, optional): Profile to use for config file.

temporal CLI global flags - output and logging

Global flags for temporal CLI output and logging: --color (string-enum, optional, default auto): Output coloring, accepted values: always, never, auto; --command-timeout (duration, optional): Command execution timeout, 0s means no timeout; --grpc-meta (string[], optional): HTTP headers for requests, KEY=VALUE format, can also be set via TEMPORAL_GRPC_META_[name]; --identity (string, optional): Identity of user or client submitting request, defaults to temporal-cli:$USER@$HOST; --log-format (string-enum, optional, default text): Log format, accepted values: text, json; --log-level (string-enum, optional, default never for most commands, warn for server start-dev): Log level, accepted values: debug, info, warn, error, never; --no-json-shorthand-payloads (bool, optional): Raw payload output, even if JSON option used; --output/-o (string-enum, optional, default text): Non-logging data output format, accepted values: text, json, jsonl, none; --time-format (string-enum, optional, default relative): Time format, accepted values: relative, iso, raw.

ClientEnvConfig.LoadClientConnectOptions works with local dev server and Temporal Cloud

ClientEnvConfig.LoadClientConnectOptions() responds to environment variables and TOML configuration files, allowing the same code to work against a local dev server and Temporal Cloud without changes. Environment variables can configure connection details, namespace, TLS certificates, and API keys.

Standalone Activities work with Temporal Cloud via envconfig

Code samples using envconfig.MustLoadDefaultClientOptions() work against both local dev servers and Temporal Cloud without code changes. The same code works against Temporal Cloud by configuring the connection via environment variables or a TOML profile.

Temporal Client functions

A Temporal Client acts as the bridge for communication between your applications and the Temporal Service. The most common operations enabled are: get the result of Workflow Execution, list Workflow Executions, query a Workflow Execution, signal a Workflow Execution, and start a Workflow Execution. Developers use the Client as the main entry point for interacting with the application through Temporal.

Workflow result retrieval

The result of a Workflow can be retrieved using a Temporal Client after the Workflow code has completed execution.

Give your agent this brain