Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

16.8 KB
Raw Blame
//! Shared client for starting PostHog Python workflows from Rust services.
//!
//! Temporal payload encryption is application-defined rather than provided by
//! the SDK. This crate emits the same Fernet-wrapped `binary/encrypted` payloads
//! as `posthog.temporal.common.codec.EncryptionCodec`.

use std::collections::HashMap;
use std::time::Duration;

use base64::{engine::general_purpose, Engine};
use fernet::Fernet;
use prost14::Message;
use serde::Serialize;
use temporalio_client::grpc::WorkflowService;
use temporalio_client::tonic::{Code, IntoRequest};
use temporalio_client::{
    Client, ClientOptions, ClientTlsOptions, Connection, ConnectionOptions, TlsOptions,
};
use temporalio_common::protos::temporal::api::common::v1::{Payload, Payloads, WorkflowType};
use temporalio_common::protos::temporal::api::enums::v1::TaskQueueKind;
pub use temporalio_common::protos::temporal::api::enums::v1::{
    WorkflowIdConflictPolicy, WorkflowIdReusePolicy,
};
use temporalio_common::protos::temporal::api::taskqueue::v1::TaskQueue;
use temporalio_common::protos::temporal::api::workflowservice::v1::StartWorkflowExecutionRequest;
use thiserror::Error;

/// Connection and encryption settings for a PostHog Temporal namespace.
#[derive(Clone, Debug)]
pub struct TemporalClientConfig {
    pub host: String,
    pub port: u16,
    pub namespace: String,
    pub client_cert: String,
    pub client_key: String,
    pub server_root_ca_cert: Option<String>,
    pub payload_encryption_key: String,
    pub identity: String,
    /// Connect without TLS. Only the local dev stack serves plaintext gRPC.
    pub insecure: bool,
}

impl TemporalClientConfig {
    /// mTLS settings, or `None` when the caller asked for a plaintext connection.
    ///
    /// A missing certificate is an error rather than an implicit downgrade, so a
    /// credential mount that renders empty fails at boot instead of dropping TLS
    /// silently. The local dev stack serves plaintext gRPC and sets `insecure`.
    fn tls_options(&self) -> Result<Option<TlsOptions>, TemporalClientError> {
        if self.insecure {
            if !self.client_cert.is_empty() || !self.client_key.is_empty() {
                return Err(TemporalClientError::ConflictingConfig(
                    "TEMPORAL_INSECURE is set alongside a client certificate",
                ));
            }
            return Ok(None);
        }

        require_config("TEMPORAL_CLIENT_CERT", &self.client_cert)?;
        require_config("TEMPORAL_CLIENT_KEY", &self.client_key)?;

        Ok(Some(TlsOptions {
            server_root_ca_cert: self
                .server_root_ca_cert
                .as_ref()
                .filter(|value| !value.is_empty())
                .map(|value| value.as_bytes().to_vec()),
            domain: Some(self.host.clone()),
            client_tls_options: Some(ClientTlsOptions {
                client_cert: self.client_cert.as_bytes().to_vec(),
                client_private_key: self.client_key.as_bytes().to_vec(),
            }),
            server_cert_verifier: None,
        }))
    }
}

/// Options that identify and route one workflow execution.
#[derive(Clone, Debug)]
pub struct StartWorkflowOptions {
    pub workflow_name: String,
    pub task_queue: String,
    pub workflow_id: String,
    pub request_id: String,
    pub id_reuse_policy: WorkflowIdReusePolicy,
    pub id_conflict_policy: WorkflowIdConflictPolicy,
    pub execution_timeout: Option<Duration>,
    pub run_timeout: Option<Duration>,
    pub task_timeout: Option<Duration>,
}

impl StartWorkflowOptions {
    /// Build options for an idempotent start. Active executions are reused and
    /// only failed closed executions may reuse the workflow ID.
    pub fn idempotent(
        workflow_name: impl Into<String>,
        task_queue: impl Into<String>,
        workflow_id: impl Into<String>,
        request_id: impl Into<String>,
    ) -> Self {
        Self {
            workflow_name: workflow_name.into(),
            task_queue: task_queue.into(),
            workflow_id: workflow_id.into(),
            request_id: request_id.into(),
            id_reuse_policy: WorkflowIdReusePolicy::AllowDuplicateFailedOnly,
            id_conflict_policy: WorkflowIdConflictPolicy::UseExisting,
            execution_timeout: None,
            run_timeout: None,
            task_timeout: None,
        }
    }
}

#[derive(Clone, Debug, PartialEq, Eq)]
pub enum StartWorkflowOutcome {
    Started { run_id: String },
    Existing { run_id: Option<String> },
}

#[derive(Debug, Error)]
pub enum TemporalClientError {
    #[error("missing Temporal client configuration: {0}")]
    MissingConfig(&'static str),
    #[error("conflicting Temporal client configuration: {0}")]
    ConflictingConfig(&'static str),
    #[error("invalid Temporal target: {0}")]
    InvalidTarget(#[from] url::ParseError),
    #[error("invalid Temporal payload encryption key: {0}")]
    InvalidEncryptionKey(String),
    #[error("failed to connect to Temporal: {0}")]
    Connect(#[from] temporalio_client::errors::ClientConnectError),
    #[error("failed to create Temporal client: {0}")]
    CreateClient(#[from] temporalio_client::errors::ClientNewError),
    #[error("failed to serialize workflow input: {0}")]
    Serialize(#[from] serde_json::Error),
    #[error("invalid workflow start options: {0}")]
    InvalidStartOptions(&'static str),
    #[error("failed to start workflow: {0}")]
    Start(temporalio_client::tonic::Status),
}

/// A cheap-to-clone, namespace-bound Temporal client that serializes Rust
/// inputs for Python workflows and encrypts them with PostHog's payload codec.
#[derive(Clone)]
pub struct TemporalWorkflowClient {
    client: Client,
    identity: String,
    encryption_key: Fernet,
}

impl TemporalWorkflowClient {
    pub async fn connect(config: TemporalClientConfig) -> Result<Self, TemporalClientError> {
        require_config("TEMPORAL_HOST", &config.host)?;
        require_config("TEMPORAL_NAMESPACE", &config.namespace)?;
        require_config("TEMPORAL_SECRET_KEY", &config.payload_encryption_key)?;
        require_config("identity", &config.identity)?;

        let tls = config.tls_options()?;
        let scheme = if tls.is_some() { "https" } else { "http" };
        let target = url::Url::parse(&format!("{scheme}://{}:{}", config.host, config.port))?;

        // The builder is typestate-based, so `tls_options` changes its type and the
        // two arms cannot share one binding.
        let connection_options = match tls {
            Some(tls) => ConnectionOptions::new(target)
                .identity(config.identity.clone())
                .tls_options(tls)
                .build(),
            None => ConnectionOptions::new(target)
                .identity(config.identity.clone())
                .build(),
        };
        let connection = Connection::connect(connection_options).await?;
        let client = Client::new(connection, ClientOptions::new(config.namespace).build())?;

        Ok(Self {
            client,
            identity: config.identity,
            encryption_key: temporal_encryption_key(&config.payload_encryption_key)?,
        })
    }

    /// Start a workflow using Temporal's stable request and workflow ID
    /// deduplication. `AlreadyExists` is returned as a successful outcome.
    pub async fn start_workflow<T: Serialize>(
        &self,
        input: &T,
        options: &StartWorkflowOptions,
    ) -> Result<StartWorkflowOutcome, TemporalClientError> {
        validate_start_options(options)?;
        let request = build_start_request(
            input,
            &self.client.options().namespace,
            &self.identity,
            options,
            &self.encryption_key,
        )?;

        match self
            .client
            .clone()
            .start_workflow_execution(request.into_request())
            .await
        {
            Ok(response) => {
                let response = response.into_inner();
                if response.started {
                    Ok(StartWorkflowOutcome::Started {
                        run_id: response.run_id,
                    })
                } else {
                    Ok(StartWorkflowOutcome::Existing {
                        run_id: Some(response.run_id),
                    })
                }
            }
            Err(status) if status.code() == Code::AlreadyExists => {
                Ok(StartWorkflowOutcome::Existing { run_id: None })
            }
            Err(status) => Err(TemporalClientError::Start(status)),
        }
    }
}

fn build_start_request<T: Serialize>(
    input: &T,
    namespace: &str,
    identity: &str,
    options: &StartWorkflowOptions,
    encryption_key: &Fernet,
) -> Result<StartWorkflowExecutionRequest, TemporalClientError> {
    let payload = encrypted_json_payload(input, encryption_key)?;
    Ok(StartWorkflowExecutionRequest {
        namespace: namespace.to_string(),
        workflow_id: options.workflow_id.clone(),
        workflow_type: Some(WorkflowType {
            name: options.workflow_name.clone(),
        }),
        task_queue: Some(TaskQueue {
            name: options.task_queue.clone(),
            kind: TaskQueueKind::Unspecified as i32,
            normal_name: String::new(),
        }),
        input: Some(Payloads {
            payloads: vec![payload],
        }),
        request_id: options.request_id.clone(),
        workflow_id_reuse_policy: options.id_reuse_policy as i32,
        workflow_id_conflict_policy: options.id_conflict_policy as i32,
        workflow_execution_timeout: options
            .execution_timeout
            .and_then(|value| value.try_into().ok()),
        workflow_run_timeout: options.run_timeout.and_then(|value| value.try_into().ok()),
        workflow_task_timeout: options.task_timeout.and_then(|value| value.try_into().ok()),
        identity: identity.to_string(),
        ..Default::default()
    })
}

fn encrypted_json_payload<T: Serialize>(
    value: &T,
    key: &Fernet,
) -> Result<Payload, TemporalClientError> {
    let plain_payload = Payload {
        metadata: HashMap::from([("encoding".to_string(), b"json/plain".to_vec())]),
        data: serde_json::to_vec(value)?,
        ..Default::default()
    };
    let token = key.encrypt(&plain_payload.encode_to_vec());
    Ok(Payload {
        metadata: HashMap::from([("encoding".to_string(), b"binary/encrypted".to_vec())]),
        data: token.into_bytes(),
        ..Default::default()
    })
}

/// Mirrors `posthog.temporal.common.codec._load_as_bytes` and `_prepare_key`.
/// Legacy raw keys and truncation to 32 bytes are intentional compatibility
/// behavior: deriving a stricter key here would make Python workers unable to
/// decrypt Rust-produced payloads.
fn temporal_encryption_key(raw: &str) -> Result<Fernet, TemporalClientError> {
    let loaded = if let Some(value) = raw.strip_prefix("hex:") {
        hex::decode(value)
            .map_err(|error| TemporalClientError::InvalidEncryptionKey(error.to_string()))?
    } else if let Some(value) = raw.strip_prefix("base64-urlsafe:") {
        general_purpose::URL_SAFE
            .decode(value)
            .map_err(|error| TemporalClientError::InvalidEncryptionKey(error.to_string()))?
    } else if let Some(value) = raw.strip_prefix("base64:") {
        general_purpose::STANDARD
            .decode(value)
            .map_err(|error| TemporalClientError::InvalidEncryptionKey(error.to_string()))?
    } else {
        raw.as_bytes().to_vec()
    };
    if loaded.len() < 32 {
        return Err(TemporalClientError::InvalidEncryptionKey(format!(
            "expected at least 32 bytes, got {}",
            loaded.len()
        )));
    }

    let prepared = general_purpose::URL_SAFE.encode(&loaded[..32]);
    Fernet::new(&prepared).ok_or_else(|| {
        TemporalClientError::InvalidEncryptionKey("failed to prepare Fernet key".to_string())
    })
}

fn validate_start_options(options: &StartWorkflowOptions) -> Result<(), TemporalClientError> {
    if options.workflow_name.is_empty() {
        return Err(TemporalClientError::InvalidStartOptions(
            "workflow_name is empty",
        ));
    }
    if options.task_queue.is_empty() {
        return Err(TemporalClientError::InvalidStartOptions(
            "task_queue is empty",
        ));
    }
    if options.workflow_id.is_empty() {
        return Err(TemporalClientError::InvalidStartOptions(
            "workflow_id is empty",
        ));
    }
    if options.request_id.is_empty() {
        return Err(TemporalClientError::InvalidStartOptions(
            "request_id is empty",
        ));
    }
    Ok(())
}

fn require_config(name: &'static str, value: &str) -> Result<(), TemporalClientError> {
    if value.is_empty() {
        return Err(TemporalClientError::MissingConfig(name));
    }
    Ok(())
}

#[cfg(test)]
mod tests {
    use prost14::Message;
    use serde::Serialize;

    use super::*;

    #[derive(Serialize)]
    struct TestInput<'a> {
        team_id: i32,
        name: &'a str,
    }

    fn config(client_cert: &str, client_key: &str, insecure: bool) -> TemporalClientConfig {
        TemporalClientConfig {
            host: "temporal".to_string(),
            port: 7233,
            namespace: "default".to_string(),
            client_cert: client_cert.to_string(),
            client_key: client_key.to_string(),
            server_root_ca_cert: None,
            payload_encryption_key: "key".to_string(),
            identity: "test".to_string(),
            insecure,
        }
    }

    #[test]
    fn tls_is_required_unless_the_caller_asked_for_plaintext() {
        assert!(config("cert", "key", false)
            .tls_options()
            .unwrap()
            .is_some());
        assert!(config("", "", true).tls_options().unwrap().is_none());

        // An empty credential must fail closed. A secret that renders empty is
        // the case this protects: without it, TLS would be dropped silently.
        for (cert, key, missing) in [
            ("", "", "TEMPORAL_CLIENT_CERT"),
            ("cert", "", "TEMPORAL_CLIENT_KEY"),
            ("", "key", "TEMPORAL_CLIENT_CERT"),
        ] {
            let error = config(cert, key, false).tls_options().unwrap_err();
            assert!(
                matches!(error, TemporalClientError::MissingConfig(name) if name == missing),
                "expected {missing}, got {error}"
            );
        }
    }

    #[test]
    fn plaintext_alongside_a_certificate_is_rejected() {
        let error = config("cert", "key", true).tls_options().unwrap_err();
        assert!(
            matches!(error, TemporalClientError::ConflictingConfig(_)),
            "expected a conflict, got {error}"
        );
    }

    fn options() -> StartWorkflowOptions {
        StartWorkflowOptions::idempotent(
            "python-workflow",
            "python-task-queue",
            "workflow-id",
            "request-id",
        )
    }

    #[test]
    fn builds_encrypted_python_workflow_request() {
        let key = temporal_encryption_key(&"a".repeat(32)).unwrap();
        let request = build_start_request(
            &TestInput {
                team_id: 42,
                name: "test",
            },
            "posthog.prod",
            "rust-service",
            &options(),
            &key,
        )
        .unwrap();

        assert_eq!(request.namespace, "posthog.prod");
        assert_eq!(request.workflow_id, "workflow-id");
        assert_eq!(request.request_id, "request-id");
        assert_eq!(request.workflow_type.unwrap().name, "python-workflow");
        assert_eq!(request.task_queue.unwrap().name, "python-task-queue");
        assert_eq!(
            request.workflow_id_reuse_policy,
            WorkflowIdReusePolicy::AllowDuplicateFailedOnly as i32
        );
        assert_eq!(
            request.workflow_id_conflict_policy,
            WorkflowIdConflictPolicy::UseExisting as i32
        );

        let payload = &request.input.unwrap().payloads[0];
        let token = std::str::from_utf8(&payload.data).unwrap();
        let inner = Payload::decode(key.decrypt(token).unwrap().as_slice()).unwrap();
        let value: serde_json::Value = serde_json::from_slice(&inner.data).unwrap();
        assert_eq!(payload.metadata["encoding"], b"binary/encrypted");
        assert_eq!(inner.metadata["encoding"], b"json/plain");
        assert_eq!(value["team_id"], 42);
        assert_eq!(value["name"], "test");
    }

    #[test]
    fn legacy_long_keys_match_python_truncation() {
        let long_key = temporal_encryption_key(&"a".repeat(40)).unwrap();
        let truncated_key = temporal_encryption_key(&"a".repeat(32)).unwrap();
        let token = long_key.encrypt(b"payload");

        assert_eq!(truncated_key.decrypt(&token).unwrap(), b"payload");
    }

    #[test]
    fn rejects_empty_idempotency_fields() {
        let mut options = options();
        options.request_id.clear();

        assert!(matches!(
            validate_start_options(&options),
            Err(TemporalClientError::InvalidStartOptions(
                "request_id is empty"
            ))
        ));
    }
}