# "Temporal Integration"

_Path: en/temporal/overview_

> "Wippy integrates with Temporal.io for durable workflow execution, automatic replay, and long-running processes that survive restarts."

## Table of Contents

- Temporal Integration

## Content

# Temporal Integration


This page is a configuration reference for Temporal clients and workers. The final registry fragment shows how the entries connect; it is not a standalone project.

The `temporal.client` and `temporal.worker` entry kinds connect Wippy workflows and activities to [Temporal](https://temporal.io).



## Client Configuration


The `temporal.client` entry kind defines a connection to a Temporal server.

```yaml
- name: temporal_client
  kind: temporal.client
  address: "localhost:7233"
  namespace: "default"
  lifecycle:
    auto_start: true
```



### Required Fields


| Field | Description |
|-------|-------------|
| `address` | Temporal server address (host:port) |



### Optional Fields


| Field | Default | Description |
|-------|---------|-------------|
| `namespace` | "default" | Temporal namespace |
| `tq_prefix` | "" | Task queue name prefix for all operations |
| `connection_timeout` | "10s" | Connection timeout |
| `keep_alive_time` | "30s" | Keep-alive interval |
| `keep_alive_timeout` | "10s" | Keep-alive timeout |



#### No Authentication


```yaml
- name: temporal_client
  kind: temporal.client
  address: "localhost:7233"
  auth:
    type: none
```



#### API Key (Temporal Cloud)


Provide the API key via one of these methods:

```yaml


# Direct value

- name: temporal_client
  kind: temporal.client
  address: "your-namespace.tmprl.cloud:7233"
  namespace: "your-namespace"
  auth:
    type: api_key
    api_key: "your-api-key"



# From environment variable

- name: temporal_client
  kind: temporal.client
  address: "your-namespace.tmprl.cloud:7233"
  namespace: "your-namespace"
  auth:
    type: api_key
    api_key: ${env:TEMPORAL_API_KEY}



# From file

- name: temporal_client
  kind: temporal.client
  address: "your-namespace.tmprl.cloud:7233"
  namespace: "your-namespace"
  auth:
    type: api_key
    api_key_file: "/etc/secrets/temporal-api-key"
```

Auth and credential fields resolve `${env:NAME}` placeholders through the [environment registry](system/env.md) at decode time. The legacy `api_key_env` / `key_pem_env` directives resolve the same way but are deprecated; prefer `api_key: ${env:NAME}` / `key_pem: ${env:NAME}`.



#### mTLS


```yaml
- name: temporal_client
  kind: temporal.client
  address: "temporal.example.com:7233"
  namespace: "production"
  auth:
    type: mtls
    cert_file: "/path/to/client.pem"
    key_file: "/path/to/client.key"
  tls:
    enabled: true
    ca_file: "/path/to/ca.pem"
```

Certificate and key can also be provided as PEM strings or from environment:

```yaml
auth:
  type: mtls
  cert_pem: |
    -----BEGIN CERTIFICATE-----
    ...
    -----END CERTIFICATE-----
  key_pem: ${env:TEMPORAL_CLIENT_KEY}
```



### TLS Configuration


```yaml
tls:
  enabled: true
  ca_file: "/path/to/ca.pem"
  server_name: "temporal.example.com"    # Override server name verification
  insecure_skip_verify: false            # Skip verification (dev only)
```



### Health Checks


```yaml
health_check:
  enabled: true
  interval: "30s"
```



### Security Context Propagation


Wippy propagates the calling actor and scope to workflows and activities as a signed Temporal header. Signing is HMAC-SHA256 with a key held by the client entry:

```yaml
- name: temporal_client
  kind: temporal.client
  address: "localhost:7233"
  security_hmac_key: ${env:TEMPORAL_SECURITY_KEY}
  security_hmac_previous_keys:
    - ${env:TEMPORAL_SECURITY_KEY_PREVIOUS}
```

| Field | Description |
|-------|-------------|
| `security_hmac_key` | Base64-encoded signing key; must decode to at least 32 bytes |
| `security_hmac_previous_keys` | Base64-encoded keys still accepted for verification, for rotation |

Both fields are base64 in YAML because they are byte fields. A key shorter than 32 decoded bytes is rejected at config validation, as is declaring `security_hmac_previous_keys` without `security_hmac_key`. New headers are always signed with `security_hmac_key`; every listed previous key is tried when verifying, so rotation is: add the new key as `security_hmac_key`, move the old one into `security_hmac_previous_keys`, then drop it once no in-flight execution carries it.

**Starting a workflow under an actor or scope requires the key.** If the caller has a security context and the client has no signing key, the header cannot be signed and the start fails. A client with no key can only start workflows from a context that carries neither an actor nor a scope.

The worker acquires the keys from the client entry it references, so a worker inherits signing and verification from `client:` without configuring anything itself. See [Workflows](temporal/workflows.md#security-context) and [Activities](temporal/activities.md).



## Worker Configuration


The `temporal.worker` entry kind defines a worker that executes workflows and activities.

```yaml
- name: worker
  kind: temporal.worker
  client: app:temporal_client
  task_queue: "my-app-queue"
  lifecycle:
    auto_start: true
    requires:
      - app:temporal_client
```



### Required Fields


| Field | Description |
|-------|-------------|
| `client` | Reference to a `temporal.client` entry |
| `task_queue` | Task queue name |



### Worker Options


Configure worker behavior:

```yaml
- name: worker
  kind: temporal.worker
  client: app:temporal_client
  task_queue: "my-app-queue"
  worker_options:
    # Identity
    identity: ""                          # Worker identity (appears in Temporal UI)

    # Concurrency
    max_concurrent_activity_execution_size: 1000
    max_concurrent_workflow_task_execution_size: 1000
    max_concurrent_local_activity_execution_size: 1000
    max_concurrent_session_execution_size: 1000
    max_concurrent_eager_activity_execution_size: 0

    # Pollers
    max_concurrent_activity_task_pollers: 20
    max_concurrent_workflow_task_pollers: 20

    # Rate limiting
    worker_activities_per_second: 0        # 0 = unlimited
    worker_local_activities_per_second: 0
    task_queue_activities_per_second: 0

    # Timeouts
    sticky_schedule_to_start_timeout: "5s"
    worker_stop_timeout: "0s"
    deadlock_detection_timeout: "0s"
    max_heartbeat_throttle_interval: "0s"
    default_heartbeat_throttle_interval: "0s"

    # Feature flags
    enable_logging_in_replay: false
    enable_session_worker: false
    disable_workflow_worker: false
    local_activity_worker_only: false
    disable_eager_activities: false
    disable_registration_aliasing: false

    # Versioning
    deployment_name: ""
    build_id: ${env:BUILD_ID}              # Read from env registry
    use_versioning: false
    default_versioning_behavior: "pinned" # or "auto_upgrade"
```

Credential and identifier fields resolve `${env:NAME}` placeholders through the [environment registry](system/env.md) at decode time. The legacy `build_id_env` directive resolves the same way but is deprecated; prefer `build_id: ${env:NAME}`.



### Versioning Behavior


`default_versioning_behavior` controls how new workflow runs pick a worker build ID when `use_versioning` is enabled:

| Value | Behavior |
|-------|----------|
| `pinned` | Workflow stays on the build ID it started on for its entire run |
| `auto_upgrade` | Workflow may resume on the latest compatible build ID after each task |

`build_id: ${env:NAME}` reads the build ID from the env registry when a literal `build_id` is not supplied.



### Session Worker


`enable_session_worker: true` lets the worker run Temporal Sessions: a series of activities pinned to a single worker (useful when activities share local state like a temp directory or open connection). `max_concurrent_session_execution_size` caps concurrent sessions on the worker.



### Concurrency Defaults


| Option | Default |
|--------|---------|
| `max_concurrent_activity_execution_size` | 1000 |
| `max_concurrent_workflow_task_execution_size` | 1000 |
| `max_concurrent_local_activity_execution_size` | 1000 |
| `max_concurrent_session_execution_size` | 1000 |
| `max_concurrent_activity_task_pollers` | 20 |
| `max_concurrent_workflow_task_pollers` | 20 |
| `sticky_schedule_to_start_timeout` | 5s |



## Configuration Example


This registry fragment connects one workflow and one activity to a worker. It assumes a reachable Temporal server at `localhost:7233` and the two referenced Lua source files; see the workflow and activity pages for their implementations.

```yaml
version: "1.0"
namespace: app

entries:
  - name: temporal_client
    kind: temporal.client
    address: "localhost:7233"
    namespace: "default"
    lifecycle:
      auto_start: true

  - name: worker
    kind: temporal.worker
    client: app:temporal_client
    task_queue: "orders"
    lifecycle:
      auto_start: true
      requires:
        - app:temporal_client

  - name: order_workflow
    kind: workflow.lua
    source: file://order_workflow.lua
    method: main
    modules:
      - funcs
      - time
    meta:
      temporal:
        workflow:
          worker: app:worker

  - name: charge_payment
    kind: function.lua
    source: file://payment.lua
    method: charge
    modules:
      - env
      - errors
      - http_client
      - json
    meta:
      temporal:
        activity:
          worker: app:worker
```



## See Also


- [Activities](temporal/activities.md) - Activity definitions
- [Workflows](temporal/workflows.md) - Workflow implementation



## Navigation

Previous: "Debugging Wippy FE" (frontend/micro-frontends/debugging)
Next: "Activities" (temporal/activities)