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.

feat(personhog): generate the lifecycle stubs for Python (#125031)

Nick Best7c7e38d0f52b
diff --git a/bin/generate_personhog_proto.sh b/bin/generate_personhog_proto.sh
index 6d6275d30db8..a1d3fb1781a5 100755
--- a/bin/generate_personhog_proto.sh
+++ b/bin/generate_personhog_proto.sh
@@ -11,7 +11,13 @@ python -c "import grpc_tools" 2>/dev/null || { echo "Error: grpcio-tools is not
echo "Cleaning old generated files..."
rm -rf "$OUT_DIR/personhog"
-mapfile -d '' PROTO_FILES < <(find "$PROTO_DIR/personhog/service" "$PROTO_DIR/personhog/types" -name '*.proto' -print0)
+# The facade, the lifecycle sagas and the types they share. Django never talks to the leader or
+# the replica directly, and it reaches the identity server only through the lifecycle service, so
+# those protos stay out: with no identity stubs the ingestion RPCs cannot be called from Python.
+mapfile -d '' PROTO_FILES < <(
+ find "$PROTO_DIR/personhog/service" "$PROTO_DIR/personhog/lifecycle" "$PROTO_DIR/personhog/types" \
+ -name '*.proto' -print0 | sort -z
+)
echo "Generating Python protobuf and gRPC stubs..."
python -m grpc_tools.protoc \
diff --git a/packages/personhog-proto/personhog/lifecycle/__init__.py b/packages/personhog-proto/personhog/lifecycle/__init__.py
new file mode 100644
index 000000000000..e69de29bb2d1
diff --git a/packages/personhog-proto/personhog/lifecycle/v1/__init__.py b/packages/personhog-proto/personhog/lifecycle/v1/__init__.py
new file mode 100644
index 000000000000..e69de29bb2d1
diff --git a/packages/personhog-proto/personhog/lifecycle/v1/lifecycle_pb2.py b/packages/personhog-proto/personhog/lifecycle/v1/lifecycle_pb2.py
new file mode 100644
index 000000000000..1d95db1477ff
--- /dev/null
+++ b/packages/personhog-proto/personhog/lifecycle/v1/lifecycle_pb2.py
@@ -0,0 +1,42 @@
+# Generated by the protocol buffer compiler. DO NOT EDIT!
+# NO CHECKED-IN PROTOBUF GENCODE
+# source: personhog/lifecycle/v1/lifecycle.proto
+# Protobuf Python Version: 6.31.1
+"""Generated protocol buffer code."""
+
+from google.protobuf import (
+ descriptor as _descriptor,
+ descriptor_pool as _descriptor_pool,
+ runtime_version as _runtime_version,
+ symbol_database as _symbol_database,
+)
+from google.protobuf.internal import builder as _builder
+
+_runtime_version.ValidateProtobufRuntimeVersion(
+ _runtime_version.Domain.PUBLIC, 6, 31, 1, "", "personhog/lifecycle/v1/lifecycle.proto"
+)
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(
+ b'\n&personhog/lifecycle/v1/lifecycle.proto\x12\x16personhog.lifecycle.v1"J\n\x14\x44\x65letePersonsRequest\x12\x0f\n\x07team_id\x18\x01 \x01(\x03\x12\x12\n\nperson_ids\x18\x02 \x03(\x03\x12\r\n\x05op_id\x18\x03 \x01(\t"\x95\x01\n\x12\x44\x65letePersonResult\x12\x11\n\tperson_id\x18\x01 \x01(\x03\x12<\n\x07outcome\x18\x02 \x01(\x0e\x32+.personhog.lifecycle.v1.DeletePersonOutcome\x12\x1b\n\x0eperson_version\x18\x03 \x01(\x03H\x00\x88\x01\x01\x42\x11\n\x0f_person_version"c\n\x15\x44\x65letePersonsResponse\x12\r\n\x05op_id\x18\x01 \x01(\t\x12;\n\x07results\x18\x02 \x03(\x0b\x32*.personhog.lifecycle.v1.DeletePersonResult*\xb0\x01\n\x13\x44\x65letePersonOutcome\x12%\n!DELETE_PERSON_OUTCOME_UNSPECIFIED\x10\x00\x12!\n\x1d\x44\x45LETE_PERSON_OUTCOME_DELETED\x10\x01\x12*\n&DELETE_PERSON_OUTCOME_SKIPPED_CONFLICT\x10\x02\x12#\n\x1f\x44\x45LETE_PERSON_OUTCOME_NOT_FOUND\x10\x03\x32\x82\x01\n\x12PersonHogLifecycle\x12l\n\rDeletePersons\x12,.personhog.lifecycle.v1.DeletePersonsRequest\x1a-.personhog.lifecycle.v1.DeletePersonsResponseb\x06proto3'
+)
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, "personhog.lifecycle.v1.lifecycle_pb2", _globals)
+if not _descriptor._USE_C_DESCRIPTORS:
+ DESCRIPTOR._loaded_options = None
+ _globals["_DELETEPERSONOUTCOME"]._serialized_start = 396
+ _globals["_DELETEPERSONOUTCOME"]._serialized_end = 572
+ _globals["_DELETEPERSONSREQUEST"]._serialized_start = 66
+ _globals["_DELETEPERSONSREQUEST"]._serialized_end = 140
+ _globals["_DELETEPERSONRESULT"]._serialized_start = 143
+ _globals["_DELETEPERSONRESULT"]._serialized_end = 292
+ _globals["_DELETEPERSONSRESPONSE"]._serialized_start = 294
+ _globals["_DELETEPERSONSRESPONSE"]._serialized_end = 393
+ _globals["_PERSONHOGLIFECYCLE"]._serialized_start = 575
+ _globals["_PERSONHOGLIFECYCLE"]._serialized_end = 705
+# @@protoc_insertion_point(module_scope)
diff --git a/packages/personhog-proto/personhog/lifecycle/v1/lifecycle_pb2.pyi b/packages/personhog-proto/personhog/lifecycle/v1/lifecycle_pb2.pyi
new file mode 100644
index 000000000000..feab801c4521
--- /dev/null
+++ b/packages/personhog-proto/personhog/lifecycle/v1/lifecycle_pb2.pyi
@@ -0,0 +1,69 @@
+from collections.abc import (
+ Iterable as _Iterable,
+ Mapping as _Mapping,
+)
+from typing import (
+ ClassVar as _ClassVar,
+ Optional as _Optional,
+ Union as _Union,
+)
+
+from google.protobuf import (
+ descriptor as _descriptor,
+ message as _message,
+)
+from google.protobuf.internal import (
+ containers as _containers,
+ enum_type_wrapper as _enum_type_wrapper,
+)
+
+DESCRIPTOR: _descriptor.FileDescriptor
+
+class DeletePersonOutcome(int, metaclass=_enum_type_wrapper.EnumTypeWrapper):
+ __slots__ = ()
+ DELETE_PERSON_OUTCOME_UNSPECIFIED: _ClassVar[DeletePersonOutcome]
+ DELETE_PERSON_OUTCOME_DELETED: _ClassVar[DeletePersonOutcome]
+ DELETE_PERSON_OUTCOME_SKIPPED_CONFLICT: _ClassVar[DeletePersonOutcome]
+ DELETE_PERSON_OUTCOME_NOT_FOUND: _ClassVar[DeletePersonOutcome]
+
+DELETE_PERSON_OUTCOME_UNSPECIFIED: DeletePersonOutcome
+DELETE_PERSON_OUTCOME_DELETED: DeletePersonOutcome
+DELETE_PERSON_OUTCOME_SKIPPED_CONFLICT: DeletePersonOutcome
+DELETE_PERSON_OUTCOME_NOT_FOUND: DeletePersonOutcome
+
+class DeletePersonsRequest(_message.Message):
+ __slots__ = ("team_id", "person_ids", "op_id")
+ TEAM_ID_FIELD_NUMBER: _ClassVar[int]
+ PERSON_IDS_FIELD_NUMBER: _ClassVar[int]
+ OP_ID_FIELD_NUMBER: _ClassVar[int]
+ team_id: int
+ person_ids: _containers.RepeatedScalarFieldContainer[int]
+ op_id: str
+ def __init__(
+ self, team_id: _Optional[int] = ..., person_ids: _Optional[_Iterable[int]] = ..., op_id: _Optional[str] = ...
+ ) -> None: ...
+
+class DeletePersonResult(_message.Message):
+ __slots__ = ("person_id", "outcome", "person_version")
+ PERSON_ID_FIELD_NUMBER: _ClassVar[int]
+ OUTCOME_FIELD_NUMBER: _ClassVar[int]
+ PERSON_VERSION_FIELD_NUMBER: _ClassVar[int]
+ person_id: int
+ outcome: DeletePersonOutcome
+ person_version: int
+ def __init__(
+ self,
+ person_id: _Optional[int] = ...,
+ outcome: _Optional[_Union[DeletePersonOutcome, str]] = ...,
+ person_version: _Optional[int] = ...,
+ ) -> None: ...
+
+class DeletePersonsResponse(_message.Message):
+ __slots__ = ("op_id", "results")
+ OP_ID_FIELD_NUMBER: _ClassVar[int]
+ RESULTS_FIELD_NUMBER: _ClassVar[int]
+ op_id: str
+ results: _containers.RepeatedCompositeFieldContainer[DeletePersonResult]
+ def __init__(
+ self, op_id: _Optional[str] = ..., results: _Optional[_Iterable[_Union[DeletePersonResult, _Mapping]]] = ...
+ ) -> None: ...
diff --git a/packages/personhog-proto/personhog/lifecycle/v1/lifecycle_pb2_grpc.py b/packages/personhog-proto/personhog/lifecycle/v1/lifecycle_pb2_grpc.py
new file mode 100644
index 000000000000..eb4d2031ffbe
--- /dev/null
+++ b/packages/personhog-proto/personhog/lifecycle/v1/lifecycle_pb2_grpc.py
@@ -0,0 +1,142 @@
+# Generated by the gRPC Python protocol compiler plugin. DO NOT EDIT!
+"""Client and server classes corresponding to protobuf-defined services."""
+
+import grpc
+
+from personhog.lifecycle.v1 import lifecycle_pb2 as personhog_dot_lifecycle_dot_v1_dot_lifecycle__pb2
+
+GRPC_GENERATED_VERSION = "1.75.1"
+GRPC_VERSION = grpc.__version__
+_version_not_supported = False
+
+try:
+ from grpc._utilities import first_version_is_lower
+
+ _version_not_supported = first_version_is_lower(GRPC_VERSION, GRPC_GENERATED_VERSION)
+except ImportError:
+ _version_not_supported = True
+
+if _version_not_supported:
+ raise RuntimeError(
+ f"The grpc package installed is at version {GRPC_VERSION},"
+ + f" but the generated code in personhog/lifecycle/v1/lifecycle_pb2_grpc.py depends on"
+ + f" grpcio>={GRPC_GENERATED_VERSION}."
+ + f" Please upgrade your grpc module to grpcio>={GRPC_GENERATED_VERSION}"
+ + f" or downgrade your generated code using grpcio-tools<={GRPC_VERSION}."
+ )
+
+
+class PersonHogLifecycleStub:
+ """PersonHogLifecycle runs person-destroying operations as durable sagas:
+ all saga state lives in the lifecycle_op tables on the persons primary,
+ the service itself stays stateless.
+
+ Ack semantics: the RPC drives the saga to Completed before responding —
+ an OK response means the operation's sync-plane work is committed and the
+ owning leaders have produced the death documents. On a crash or timeout
+ the caller retries with the same op_id; the retry attaches to the
+ existing operation, finishes any incomplete tail steps, and returns the
+ recorded outcome. A background sweeper backstops abandoned operations.
+
+ Co-served on the identity server, but a separate service so callers are
+ insulated from any future split.
+ """
+
+ def __init__(self, channel):
+ """Constructor.
+
+ Args:
+ channel: A grpc.Channel.
+ """
+ self.DeletePersons = channel.unary_unary(
+ "/personhog.lifecycle.v1.PersonHogLifecycle/DeletePersons",
+ request_serializer=personhog_dot_lifecycle_dot_v1_dot_lifecycle__pb2.DeletePersonsRequest.SerializeToString,
+ response_deserializer=personhog_dot_lifecycle_dot_v1_dot_lifecycle__pb2.DeletePersonsResponse.FromString,
+ _registered_method=True,
+ )
+
+
+class PersonHogLifecycleServicer:
+ """PersonHogLifecycle runs person-destroying operations as durable sagas:
+ all saga state lives in the lifecycle_op tables on the persons primary,
+ the service itself stays stateless.
+
+ Ack semantics: the RPC drives the saga to Completed before responding —
+ an OK response means the operation's sync-plane work is committed and the
+ owning leaders have produced the death documents. On a crash or timeout
+ the caller retries with the same op_id; the retry attaches to the
+ existing operation, finishes any incomplete tail steps, and returns the
+ recorded outcome. A background sweeper backstops abandoned operations.
+
+ Co-served on the identity server, but a separate service so callers are
+ insulated from any future split.
+ """
+
+ def DeletePersons(self, request, context):
+ """Missing associated documentation comment in .proto file."""
+ context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+ context.set_details("Method not implemented!")
+ raise NotImplementedError("Method not implemented!")
+
+
+def add_PersonHogLifecycleServicer_to_server(servicer, server):
+ rpc_method_handlers = {
+ "DeletePersons": grpc.unary_unary_rpc_method_handler(
+ servicer.DeletePersons,
+ request_deserializer=personhog_dot_lifecycle_dot_v1_dot_lifecycle__pb2.DeletePersonsRequest.FromString,
+ response_serializer=personhog_dot_lifecycle_dot_v1_dot_lifecycle__pb2.DeletePersonsResponse.SerializeToString,
+ ),
+ }
+ generic_handler = grpc.method_handlers_generic_handler(
+ "personhog.lifecycle.v1.PersonHogLifecycle", rpc_method_handlers
+ )
+ server.add_generic_rpc_handlers((generic_handler,))
+ server.add_registered_method_handlers("personhog.lifecycle.v1.PersonHogLifecycle", rpc_method_handlers)
+
+
+# This class is part of an EXPERIMENTAL API.
+class PersonHogLifecycle:
+ """PersonHogLifecycle runs person-destroying operations as durable sagas:
+ all saga state lives in the lifecycle_op tables on the persons primary,
+ the service itself stays stateless.
+
+ Ack semantics: the RPC drives the saga to Completed before responding —
+ an OK response means the operation's sync-plane work is committed and the
+ owning leaders have produced the death documents. On a crash or timeout
+ the caller retries with the same op_id; the retry attaches to the
+ existing operation, finishes any incomplete tail steps, and returns the
+ recorded outcome. A background sweeper backstops abandoned operations.
+
+ Co-served on the identity server, but a separate service so callers are
+ insulated from any future split.
+ """
+
+ @staticmethod
+ def DeletePersons(
+ request,
+ target,
+ options=(),
+ channel_credentials=None,
+ call_credentials=None,
+ insecure=False,
+ compression=None,
+ wait_for_ready=None,
+ timeout=None,
+ metadata=None,
+ ):
+ return grpc.experimental.unary_unary(
+ request,
+ target,
+ "/personhog.lifecycle.v1.PersonHogLifecycle/DeletePersons",
+ personhog_dot_lifecycle_dot_v1_dot_lifecycle__pb2.DeletePersonsRequest.SerializeToString,
+ personhog_dot_lifecycle_dot_v1_dot_lifecycle__pb2.DeletePersonsResponse.FromString,
+ options,
+ channel_credentials,
+ insecure,
+ call_credentials,
+ compression,
+ wait_for_ready,
+ timeout,
+ metadata,
+ _registered_method=True,
+ )
diff --git a/posthog/personhog_client/README.md b/posthog/personhog_client/README.md
index e72e508a6d6d..bdc3c7bfb562 100644
--- a/posthog/personhog_client/README.md
+++ b/posthog/personhog_client/README.md
@@ -74,6 +74,16 @@ The `PersonHogClient` in `client.py` exposes typed methods for every RPC:
**Person split:**
`split_person` — splits distinct_ids off a person onto new persons (max 250 per request); the sole write path for person splits, with no ORM fallback
+**Lifecycle sagas (identity server):**
+`client.lifecycle.delete_persons` runs the fenced delete saga for up to 250 person ids of one team and returns one outcome per requested id (`DELETED`, `NOT_FOUND`, `SKIPPED_CONFLICT`).
+The sagas live under `client.lifecycle` because the facade has a `delete_persons` too, and the two go to places with opposite consistency: the facade writes the replica's database directly, a saga fences the person's leader first.
+They go out on a second channel to `PERSONHOG_LIFECYCLE_ADDR` (a router with the identity proxy enabled); without that setting `client.lifecycle.configured` is false and every saga method raises `PersonHogLifecycleUnavailable`.
+The lifecycle service is the only identity-server surface Django has: `bin/generate_personhog_proto.sh` emits no stubs for `personhog.identity.v1`, so the ingestion RPCs (`GetOrCreate*`, `MergePersons`) cannot be called from Python.
+The call waits for the saga to complete, so its deadline is `PERSONHOG_LIFECYCLE_TIMEOUT_MS` rather than `PERSONHOG_TIMEOUT_MS`.
+Every request carries a caller-generated `op_id`. Retry a transient failure with the same `op_id` and the identical `person_ids` list; the retry attaches to the existing operation and returns its recorded outcome.
+A `FAILED_PRECONDITION` with a reason from `semantic_refusal_reason()` (in `interceptor.py`) is final: never retry it under the same `op_id`. The identity server's own reason is `op_id_reused` (the `op_id` belongs to a different request; reissue under a fresh one). The leader's reasons (`release-unverified`, `uuid-mismatch`, `no-lifecycle-db`) pass through the saga unchanged and mean the operation cannot finish as issued; surface them rather than looping.
+The request and response types are re-exported from `posthog.personhog_client.proto` as `LifecycleDeletePersonsRequest` and `LifecycleDeletePersonsResponse`, because the facade's delete messages share their names.
+
**Version floors:**
`ensure_person_version_floors` (raise each tombstone to a minimum version, inserting a tombstone where no row exists, and leave live rows unchanged; a lost insert race fails the whole request with `FAILED_PRECONDITION`).
Each write takes at most 250 keys in one transaction. Use the helper in `posthog/models/person/util.py`: it batches and retries a lost race.
diff --git a/posthog/personhog_client/client.py b/posthog/personhog_client/client.py
index a52ea7c0b8b7..c837681c82c9 100644
--- a/posthog/personhog_client/client.py
+++ b/posthog/personhog_client/client.py
@@ -79,6 +79,8 @@ from posthog.personhog_client.proto import (
GroupTypeMappingsResponse,
InsertCohortMembersRequest,
InsertCohortMembersResponse,
+ LifecycleDeletePersonsRequest,
+ LifecycleDeletePersonsResponse,
ListCohortMemberIdsRequest,
ListCohortMemberIdsResponse,
ListGroupsRequest,
@@ -87,6 +89,7 @@ from posthog.personhog_client.proto import (
ListPersonsForTeamResponse,
ListPersonTombstoneQueueRequest,
ListPersonTombstoneQueueResponse,
+ PersonHogLifecycleStub,
PersonHogServiceStub,
PersonsByDistinctIdsInTeamResponse,
PersonsResponse,
@@ -175,12 +178,50 @@ class _ChannelStateMonitor:
pass
+class PersonHogLifecycleUnavailable(RuntimeError):
+ """The client has no lifecycle channel because PERSONHOG_LIFECYCLE_ADDR is not set."""
+
+
+class PersonHogLifecycleClient:
+ """The identity server's sagas, reached as ``client.lifecycle`` over their own channel.
+
+ The facade and the lifecycle service both have a DeletePersons, with opposite consistency: the
+ facade writes the replica's database directly, a saga fences the person's leader first. Keeping
+ the sagas behind their own namespace makes the destination visible at every call site.
+ """
+
+ def __init__(self, stub: PersonHogLifecycleStub | None, timeout: float) -> None:
+ self._stub = stub
+ self._timeout = timeout
+
+ @property
+ def configured(self) -> bool:
+ return self._stub is not None
+
+ def delete_persons(
+ self, request: LifecycleDeletePersonsRequest, timeout: float | None = None
+ ) -> LifecycleDeletePersonsResponse:
+ """Run the delete saga for up to 250 person ids of one team.
+
+ The call returns once the saga is complete: the persons are tombstoned in Postgres and their
+ leaders have produced the death documents. Retry a transient failure with the SAME op_id and
+ the byte-identical person_ids list; the retry attaches to the existing operation and returns
+ its recorded outcome. A FAILED_PRECONDITION whose ``semantic_refusal_reason`` is
+ ``op_id_reused`` means the op_id belongs to a different request and must not be retried.
+ """
+ if self._stub is None:
+ raise PersonHogLifecycleUnavailable("personhog lifecycle client not configured (PERSONHOG_LIFECYCLE_ADDR)")
+ return self._stub.DeletePersons(request, timeout=timeout or self._timeout)
+
+
class PersonHogClient:
def __init__(
self,
addr: str,
client_name: str = "posthog-django",
timeout_ms: int = 5000,
+ lifecycle_addr: str = "",
+ lifecycle_timeout_ms: int = 45_000,
keepalive_time_ms: int = 30_000,
keepalive_timeout_ms: int = 5_000,
keepalive_without_calls: bool = True,
@@ -205,26 +246,49 @@ class PersonHogClient:
# Prevent the channel from transitioning to IDLE between requests.
("grpc.client_idle_timeout_ms", client_idle_timeout_ms),
]
+ retry_interceptor = RetryInterceptor(
+ client_name,
+ max_retries=max_retries,
+ initial_backoff_ms=initial_backoff_ms,
+ max_backoff_ms=max_backoff_ms,
+ )
channel = grpc.insecure_channel(addr, options=options)
self._channel = grpc.intercept_channel(
channel,
ClientNameInterceptor(client_name),
ConsistencyHeaderInterceptor(),
- RetryInterceptor(
- client_name,
- max_retries=max_retries,
- initial_backoff_ms=initial_backoff_ms,
- max_backoff_ms=max_backoff_ms,
- ),
+ retry_interceptor,
MetricsInterceptor(client_name),
)
self._state_monitor = _ChannelStateMonitor(channel, client_name)
self._stub = PersonHogServiceStub(self._channel)
self._timeout = timeout_ms / 1000.0
+ # The identity server sits behind a different router than the facade. No consistency header:
+ # lifecycle requests have no read_options. Retries are safe: every request carries an op_id.
+ self._lifecycle_channel: grpc.Channel | None = None
+ self._lifecycle_state_monitor: _ChannelStateMonitor | None = None
+ lifecycle_stub: PersonHogLifecycleStub | None = None
+ if lifecycle_addr:
+ lifecycle_channel = grpc.insecure_channel(lifecycle_addr, options=options)
+ self._lifecycle_channel = grpc.intercept_channel(
+ lifecycle_channel,
+ ClientNameInterceptor(client_name),
+ retry_interceptor,
+ MetricsInterceptor(client_name),
+ )
+ # The channel-state gauge is keyed by client_name alone; two channels under one name would fight over it.
+ self._lifecycle_state_monitor = _ChannelStateMonitor(lifecycle_channel, f"{client_name}-lifecycle")
+ lifecycle_stub = PersonHogLifecycleStub(self._lifecycle_channel)
+ self.lifecycle = PersonHogLifecycleClient(lifecycle_stub, lifecycle_timeout_ms / 1000.0)
+
def close(self) -> None:
self._state_monitor.close()
self._channel.close()
+ if self._lifecycle_state_monitor is not None:
+ self._lifecycle_state_monitor.close()
+ if self._lifecycle_channel is not None:
+ self._lifecycle_channel.close()
# -- Person deletes --
@@ -454,11 +518,14 @@ def get_personhog_client() -> Optional[PersonHogClient]:
return None
timeout_ms = getattr(settings, "PERSONHOG_TIMEOUT_MS", 5000)
+ lifecycle_addr = getattr(settings, "PERSONHOG_LIFECYCLE_ADDR", "")
client_name = getattr(settings, "OTEL_SERVICE_NAME", None) or "posthog-django"
_client = PersonHogClient(
addr=addr,
client_name=client_name,
timeout_ms=timeout_ms,
+ lifecycle_addr=lifecycle_addr,
+ lifecycle_timeout_ms=getattr(settings, "PERSONHOG_LIFECYCLE_TIMEOUT_MS", 45_000),
keepalive_time_ms=getattr(settings, "PERSONHOG_KEEPALIVE_TIME_MS", 30_000),
keepalive_timeout_ms=getattr(settings, "PERSONHOG_KEEPALIVE_TIMEOUT_MS", 5_000),
keepalive_without_calls=getattr(settings, "PERSONHOG_KEEPALIVE_WITHOUT_CALLS", True),
@@ -471,7 +538,9 @@ def get_personhog_client() -> Optional[PersonHogClient]:
initial_backoff_ms=getattr(settings, "PERSONHOG_INITIAL_BACKOFF_MS", 50),
max_backoff_ms=getattr(settings, "PERSONHOG_MAX_BACKOFF_MS", 1000),
)
- logger.info("personhog_client_initialized", addr=addr, timeout_ms=timeout_ms)
+ logger.info(
+ "personhog_client_initialized", addr=addr, timeout_ms=timeout_ms, lifecycle_addr=lifecycle_addr
+ )
return _client
diff --git a/posthog/personhog_client/fake_client.py b/posthog/personhog_client/fake_client.py
index b5a8e148658c..509103c305d5 100644
--- a/posthog/personhog_client/fake_client.py
+++ b/posthog/personhog_client/fake_client.py
@@ -19,6 +19,7 @@ from __future__ import annotations
import json
import time
+from collections.abc import Sequence
from contextlib import contextmanager
from dataclasses import dataclass
from typing import Any
@@ -26,9 +27,12 @@ from uuid import UUID, uuid4
from unittest.mock import patch
+import grpc
+from personhog.lifecycle.v1 import lifecycle_pb2
from personhog.types.v1 import cohort_pb2, feature_flag_pb2, group_pb2, person_pb2
from posthog.models.person.missing_person import uuidFromDistinctId
+from posthog.personhog_client.interceptor import SEMANTIC_REFUSAL_METADATA_KEY
from posthog.utils import is_anonymous_id
@@ -39,6 +43,27 @@ class _Call:
response: Any = None
+class _FakeRpcError(grpc.RpcError):
+ """A failed call the way grpcio raises one: status, details and trailing metadata are methods."""
+
+ def __init__(
+ self, code: grpc.StatusCode, details: str, trailing_metadata: Sequence[tuple[str, str | bytes]] = ()
+ ) -> None:
+ super().__init__(details)
+ self._code = code
+ self._details = details
+ self._trailing_metadata = trailing_metadata
+
+ def code(self) -> grpc.StatusCode:
+ return self._code
+
+ def details(self) -> str:
+ return self._details
+
+ def trailing_metadata(self) -> Sequence[tuple[str, str | bytes]]:
+ return self._trailing_metadata
+
+
def _order_identified_first(
dids: list[person_pb2.DistinctIdWithVersion],
) -> list[person_pb2.DistinctIdWithVersion]:
@@ -56,6 +81,28 @@ VERSION_RPC_MAX_KEYS = 250
# The replica's cap on distinct ids across all persons in one restore request.
RESTORE_MAX_DISTINCT_IDS = 1000
+# The identity server's cap on person ids per lifecycle DeletePersons request.
+LIFECYCLE_DELETE_MAX_PERSON_IDS = 250
+
+# team_id is narrowed to i32 server-side.
+_MAX_TEAM_ID = 2**31 - 1
+
+
+class _FakeLifecycleClient:
+ """The fake's ``lifecycle`` namespace; the saga state lives on the fake itself."""
+
+ def __init__(self, fake: FakePersonHogClient) -> None:
+ self._fake = fake
+
+ @property
+ def configured(self) -> bool:
+ return True
+
+ def delete_persons(
+ self, request: lifecycle_pb2.DeletePersonsRequest, timeout: float | None = None
+ ) -> lifecycle_pb2.DeletePersonsResponse:
+ return self._fake._lifecycle_delete_persons(request)
+
class FakePersonHogClient:
"""In-memory fake that implements the same interface as PersonHogClient.
@@ -66,6 +113,7 @@ class FakePersonHogClient:
def __init__(self) -> None:
self.calls: list[_Call] = []
+ self.lifecycle = _FakeLifecycleClient(self)
# keyed by (team_id, person_id)
self._persons_by_id: dict[tuple[int, int], person_pb2.Person] = {}
@@ -83,6 +131,11 @@ class FakePersonHogClient:
# only, so the row budget counts them alone.
self.tombstoned_delete_max_rows = 5000
+ # by op_id: the frozen request (team, person ids as sent) and the recorded response
+ self._lifecycle_ops: dict[str, tuple[int, tuple[int, ...], lifecycle_pb2.DeletePersonsResponse]] = {}
+ # (team_id, person_id) held by another live lifecycle op
+ self._lifecycle_marks: set[tuple[int, int]] = set()
+
# keyed by project_id -> list of GroupTypeMapping
self._group_type_mappings_by_project: dict[int, list[group_pb2.GroupTypeMapping]] = {}
# keyed by team_id -> list of GroupTypeMapping
@@ -202,6 +255,10 @@ class FakePersonHogClient:
self._groups[(team_id, group_type_index, group_key)] = group
return group
+ def hold_lifecycle_mark(self, *, team_id: int, person_id: int) -> None:
+ """Make a person look held by another live lifecycle op, so a delete reports SKIPPED_CONFLICT."""
+ self._lifecycle_marks.add((team_id, person_id))
+
def add_cohort_membership(self, *, person_id: int, cohort_id: int, is_member: bool = True) -> None:
self._cohort_memberships.setdefault(person_id, []).append(
cohort_pb2.CohortMembership(cohort_id=cohort_id, is_member=is_member)
@@ -697,6 +754,74 @@ class FakePersonHogClient:
tombstoned.distinct_ids.add(distinct_id=did.distinct_id, version=did.version)
return version
+ # ── Lifecycle sagas ───────────────────────────────────────────────
+
+ def _lifecycle_delete_persons(
+ self, request: lifecycle_pb2.DeletePersonsRequest
+ ) -> lifecycle_pb2.DeletePersonsResponse:
+ self.calls.append(_Call("lifecycle.delete_persons", request))
+ self._validate_lifecycle_delete(request)
+
+ frozen = (request.team_id, tuple(request.person_ids))
+ recorded = self._lifecycle_ops.get(request.op_id)
+ if recorded is not None:
+ team_id, person_ids, response = recorded
+ if (team_id, person_ids) != frozen:
+ raise _FakeRpcError(
+ grpc.StatusCode.FAILED_PRECONDITION,
+ f"op {request.op_id} already exists with a different request",
+ ((SEMANTIC_REFUSAL_METADATA_KEY, "op_id_reused"),),
+ )
+ copy = lifecycle_pb2.DeletePersonsResponse()
+ copy.CopyFrom(response)
+ return copy
+
+ # One decision per distinct person, so a duplicated id reports the same outcome twice.
+ outcomes: dict[int, lifecycle_pb2.DeletePersonOutcome] = {}
+ for person_id in request.person_ids:
+ if person_id in outcomes:
+ continue
+ person = self._live(self._persons_by_id.get((request.team_id, person_id)))
+ if person is None:
+ outcomes[person_id] = lifecycle_pb2.DELETE_PERSON_OUTCOME_NOT_FOUND
+ elif (request.team_id, person_id) in self._lifecycle_marks:
+ outcomes[person_id] = lifecycle_pb2.DELETE_PERSON_OUTCOME_SKIPPED_CONFLICT
+ else:
+ # No publish-queue row: the death document and the outbox carry the ClickHouse tombstones.
+ self._tombstone_person(request.team_id, person, person_pb2.TombstonedPerson())
+ self._cohort_memberships.pop(person.id, None)
+ for key in [key for key in self._cohort_members if key[1] == person.id]:
+ del self._cohort_members[key]
+ outcomes[person_id] = lifecycle_pb2.DELETE_PERSON_OUTCOME_DELETED
+
+ response = lifecycle_pb2.DeletePersonsResponse(op_id=request.op_id)
+ for person_id in request.person_ids:
+ response.results.add(person_id=person_id, outcome=outcomes[person_id])
+ self._lifecycle_ops[request.op_id] = (frozen[0], frozen[1], response)
+ copy = lifecycle_pb2.DeletePersonsResponse()
+ copy.CopyFrom(response)
+ return copy
+
+ @staticmethod
+ def _validate_lifecycle_delete(request: lifecycle_pb2.DeletePersonsRequest) -> None:
+ """Mirror the identity server's request validation (rust/personhog-identity, validation.rs)."""
+ if not 0 < request.team_id <= _MAX_TEAM_ID:
+ reason = "team_id must be a positive 32-bit integer"
+ elif not request.person_ids:
+ reason = "person_ids must not be empty"
+ elif len(request.person_ids) > LIFECYCLE_DELETE_MAX_PERSON_IDS:
+ reason = f"batch size {len(request.person_ids)} exceeds maximum {LIFECYCLE_DELETE_MAX_PERSON_IDS}"
+ elif any(person_id <= 0 for person_id in request.person_ids):
+ reason = "person_ids must be positive integers"
+ else:
+ try:
+ UUID(request.op_id)
+ except ValueError:
+ reason = "op_id must be a valid UUID"
+ else:
+ return
+ raise _FakeRpcError(grpc.StatusCode.INVALID_ARGUMENT, reason)
+
def ack_person_tombstones(
self, request: person_pb2.AckPersonTombstonesRequest, timeout: float | None = None
) -> person_pb2.AckPersonTombstonesResponse:
diff --git a/posthog/personhog_client/interceptor.py b/posthog/personhog_client/interceptor.py
index 99747e050b8a..3b80d09fc3f1 100644
--- a/posthog/personhog_client/interceptor.py
+++ b/posthog/personhog_client/interceptor.py
@@ -44,10 +44,17 @@ PERSONHOG_DJANGO_REQUEST_COUNT = Counter(
)
+_FACADE_SERVICE = "personhog.service.v1.PersonHogService"
+
+
def _method_name(client_call_details: grpc.ClientCallDetails) -> str:
- # client_call_details.method is like "/personhog.service.v1.PersonHogService/GetPerson"
+ # "/personhog.service.v1.PersonHogService/GetPerson" -> "GetPerson", the label dashboards were built
+ # on. Another service keeps its short name: the facade and the lifecycle service both have DeletePersons.
method: str = client_call_details.method or "unknown"
- return method.rsplit("/", 1)[-1]
+ service, _, name = method.strip("/").rpartition("/")
+ if not service or service == _FACADE_SERVICE:
+ return name or "unknown"
+ return f"{service.rsplit('.', 1)[-1]}/{name}"
def _grpc_error_type(code: grpc.StatusCode) -> str:
@@ -166,6 +173,10 @@ _DESERIALIZATION_FAILURE_DETAILS = "Exception deserializing response!"
# Must match DB_TIMEOUT_METADATA_KEY in rust/personhog-common/src/grpc.rs.
_DB_TIMEOUT_METADATA_KEY = "x-db-timeout"
+# Must match SEMANTIC_REFUSAL_METADATA_KEY in rust/personhog-common/src/grpc.rs: a FAILED_PRECONDITION
+# carrying it is a final answer about the request itself, not a routing race that clears on retry.
+SEMANTIC_REFUSAL_METADATA_KEY = "x-semantic-refusal"
+
def _is_retryable(code: grpc.StatusCode | None, details: str | None, codes: Collection[grpc.StatusCode]) -> bool:
if code is None:
@@ -198,6 +209,29 @@ def is_transient_rpc_error(exc: BaseException, codes: Collection[grpc.StatusCode
return False
+def semantic_refusal_reason(exc: BaseException) -> str | None:
+ """The reason slug of a definitive FAILED_PRECONDITION refusal, or None for any other error.
+
+ Follows ``__cause__`` like ``is_transient_rpc_error``. Any reason is final, so a caller never retries
+ under the same op_id; it branches on the slug instead of the message. The identity server emits
+ ``op_id_reused`` (the op_id belongs to a different request); the leader's own refusals pass through
+ the saga unchanged.
+ """
+ current: BaseException | None = exc
+ while current is not None:
+ if isinstance(current, grpc.RpcError):
+ code = getattr(current, "code", None)
+ trailing = getattr(current, "trailing_metadata", None)
+ if not callable(code) or not callable(trailing) or code() != grpc.StatusCode.FAILED_PRECONDITION:
+ return None
+ for key, value in trailing() or ():
+ if key == SEMANTIC_REFUSAL_METADATA_KEY:
+ return value if isinstance(value, str) else value.decode()
+ return None
+ current = current.__cause__
+ return None
+
+
class RetryInterceptor(grpc.UnaryUnaryClientInterceptor):
"""Retries transient gRPC errors with jittered backoff.
diff --git a/posthog/personhog_client/proto/__init__.py b/posthog/personhog_client/proto/__init__.py
index d90b4cbb70d3..8c03166fbd28 100644
--- a/posthog/personhog_client/proto/__init__.py
+++ b/posthog/personhog_client/proto/__init__.py
@@ -10,6 +10,19 @@ from personhog.types.v1.common_pb2 import (
ReadOptions,
)
from personhog.service.v1.service_pb2_grpc import PersonHogServiceStub
+from personhog.lifecycle.v1.lifecycle_pb2_grpc import PersonHogLifecycleStub
+
+# Aliased: the facade's delete messages above already use these names.
+from personhog.lifecycle.v1.lifecycle_pb2 import (
+ DELETE_PERSON_OUTCOME_DELETED,
+ DELETE_PERSON_OUTCOME_NOT_FOUND,
+ DELETE_PERSON_OUTCOME_SKIPPED_CONFLICT,
+ DELETE_PERSON_OUTCOME_UNSPECIFIED,
+ DeletePersonOutcome,
+ DeletePersonResult as LifecycleDeletePersonResult,
+ DeletePersonsRequest as LifecycleDeletePersonsRequest,
+ DeletePersonsResponse as LifecycleDeletePersonsResponse,
+)
from personhog.types.v1.cohort_pb2 import (
CheckCohortMembershipRequest,
CohortMembership,
diff --git a/posthog/personhog_client/test_client.py b/posthog/personhog_client/test_client.py
new file mode 100644
index 000000000000..0459f003db56
--- /dev/null
+++ b/posthog/personhog_client/test_client.py
@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+from collections.abc import Iterator
+from concurrent.futures import ThreadPoolExecutor
+from contextlib import contextmanager
+
+import pytest
+
+import grpc
+from parameterized import parameterized
+from personhog.lifecycle.v1.lifecycle_pb2_grpc import (
+ PersonHogLifecycleServicer,
+ add_PersonHogLifecycleServicer_to_server,
+)
+
+from posthog.personhog_client.client import PersonHogClient, PersonHogLifecycleUnavailable
+from posthog.personhog_client.interceptor import semantic_refusal_reason
+from posthog.personhog_client.proto import (
+ DELETE_PERSON_OUTCOME_DELETED,
+ LifecycleDeletePersonsRequest,
+ LifecycleDeletePersonsResponse,
+)
+
+OP_ID = "6f1d2a3b-4c5d-4e6f-8a9b-0c1d2e3f4a5b"
+
+
+class _RecordingLifecycleService(PersonHogLifecycleServicer):
+ def __init__(
+ self,
+ failure: tuple[grpc.StatusCode, tuple[tuple[str, str], ...]] | None = None,
+ fail_once: bool = False,
+ ) -> None:
+ self._failure = failure
+ self._fail_once = fail_once
+ self.calls = 0
+ self.client_names: list[str] = []
+ self.time_remaining: float | None = None
+
+ def DeletePersons(self, request, context):
+ self.calls += 1
+ self.client_names.extend(value for key, value in context.invocation_metadata() if key == "x-client-name")
+ self.time_remaining = context.time_remaining()
+ if self._failure is not None and (self.calls == 1 or not self._fail_once):
+ code, trailing_metadata = self._failure
+ context.set_trailing_metadata(trailing_metadata)
+ context.abort(code, "injected failure")
+ response = LifecycleDeletePersonsResponse(op_id=request.op_id)
+ for person_id in request.person_ids:
+ response.results.add(person_id=person_id, outcome=DELETE_PERSON_OUTCOME_DELETED)
+ return response
+
+
+@contextmanager
+def _client_for(service: PersonHogLifecycleServicer) -> Iterator[PersonHogClient]:
+ with ThreadPoolExecutor(max_workers=1) as pool:
+ server = grpc.server(pool)
+ add_PersonHogLifecycleServicer_to_server(service, server)
+ port = server.add_insecure_port("localhost:0")
+ server.start()
+ # The facade address is never dialled here: gRPC channels connect on first use.
+ client = PersonHogClient(
+ "localhost:1",
+ client_name="test-client",
+ lifecycle_addr=f"localhost:{port}",
+ initial_backoff_ms=1,
+ max_backoff_ms=1,
+ )
+ try:
+ yield client
+ finally:
+ client.close()
+ server.stop(None)
+
+
+class TestLifecycleChannel:
+ def test_lifecycle_calls_go_out_on_the_lifecycle_channel_with_client_metadata_and_deadline(self):
+ service = _RecordingLifecycleService()
+
+ with _client_for(service) as client:
+ assert client.lifecycle.configured
+ response = client.lifecycle.delete_persons(
+ LifecycleDeletePersonsRequest(team_id=1, person_ids=[10, 20], op_id=OP_ID)
+ )
+
+ assert response.op_id == OP_ID
+ assert [(r.person_id, r.outcome) for r in response.results] == [
+ (10, DELETE_PERSON_OUTCOME_DELETED),
+ (20, DELETE_PERSON_OUTCOME_DELETED),
+ ]
+ assert service.client_names == ["test-client"]
+ # The lifecycle deadline, not the facade's 5 s, and above the identity server's 30 s execute timeout.
+ assert service.time_remaining is not None and service.time_remaining > 30
+
+ @parameterized.expand(
+ [
+ ("unavailable_is_retried", grpc.StatusCode.UNAVAILABLE, (), True, grpc.StatusCode.OK, 2, None),
+ (
+ "refusal_trailer_reaches_the_caller_on_the_first_call",
+ grpc.StatusCode.FAILED_PRECONDITION,
+ (("x-semantic-refusal", "op_id_reused"),),
+ False,
+ grpc.StatusCode.FAILED_PRECONDITION,
+ 1,
+ "op_id_reused",
+ ),
+ ]
+ )
+ def test_retry_decision_on_the_lifecycle_channel(
+ self,
+ _name: str,
+ failure_code: grpc.StatusCode,
+ trailing_metadata: tuple[tuple[str, str], ...],
+ fail_once: bool,
+ expected_code: grpc.StatusCode,
+ expected_calls: int,
+ expected_reason: str | None,
+ ):
+ service = _RecordingLifecycleService(failure=(failure_code, trailing_metadata), fail_once=fail_once)
+
+ with _client_for(service) as client:
+ try:
+ client.lifecycle.delete_persons(LifecycleDeletePersonsRequest(team_id=1, person_ids=[10], op_id=OP_ID))
+ code, reason = grpc.StatusCode.OK, None
+ except grpc.RpcError as exc:
+ code, reason = exc.code(), semantic_refusal_reason(exc)
+
+ assert (code, reason, service.calls) == (expected_code, expected_reason, expected_calls)
+
+ def test_without_a_lifecycle_address_the_method_refuses_instead_of_dialling_the_facade(self):
+ client = PersonHogClient("localhost:1", client_name="test-client")
+ try:
+ assert not client.lifecycle.configured
+ with pytest.raises(PersonHogLifecycleUnavailable):
+ client.lifecycle.delete_persons(LifecycleDeletePersonsRequest(team_id=1, person_ids=[10], op_id=OP_ID))
+ finally:
+ client.close()
diff --git a/posthog/personhog_client/test_fake_client.py b/posthog/personhog_client/test_fake_client.py
index 7e58d4da9533..b947427d21f5 100644
--- a/posthog/personhog_client/test_fake_client.py
+++ b/posthog/personhog_client/test_fake_client.py
@@ -2,9 +2,13 @@ import json
import pytest
+import grpc
+from parameterized import parameterized
+from personhog.lifecycle.v1 import lifecycle_pb2
from personhog.types.v1 import cohort_pb2, common_pb2, group_pb2, person_pb2
from posthog.personhog_client.fake_client import FakePersonHogClient, fake_personhog_client
+from posthog.personhog_client.interceptor import semantic_refusal_reason
class TestFakePersonHogClientPersons:
@@ -951,3 +955,112 @@ class TestFakePersonHogClientRepairWrites:
)
live = self.client.stored_person(self.TEAM_ID, self.LIVE)
assert live is not None and live.version == 2
+
+
+class TestFakePersonHogClientLifecycleDeletes:
+ TEAM_ID = 1
+ OP_A = "11111111-1111-4111-8111-111111111111"
+ OP_B = "22222222-2222-4222-8222-222222222222"
+
+ def setup_method(self):
+ self.client = FakePersonHogClient()
+ self.client.add_person(
+ team_id=self.TEAM_ID, person_id=10, uuid="abc-123", version=4, distinct_ids=["[email protected]", "anon-1"]
+ )
+ self.client.add_person(team_id=self.TEAM_ID, person_id=20, uuid="def-456", distinct_ids=["[email protected]"])
+ self.client.add_cohort_membership(person_id=10, cohort_id=7)
+
+ def _delete(self, person_ids: list[int], op_id: str = OP_A, team_id: int = TEAM_ID):
+ return self.client.lifecycle.delete_persons(
+ lifecycle_pb2.DeletePersonsRequest(team_id=team_id, person_ids=person_ids, op_id=op_id)
+ )
+
+ def test_reports_one_outcome_per_requested_id_and_tombstones_the_deleted_persons(self):
+ response = self._delete([10, 999, 10, 20])
+
+ assert response.op_id == self.OP_A
+ assert [(r.person_id, r.outcome) for r in response.results] == [
+ (10, lifecycle_pb2.DELETE_PERSON_OUTCOME_DELETED),
+ (999, lifecycle_pb2.DELETE_PERSON_OUTCOME_NOT_FOUND),
+ (10, lifecycle_pb2.DELETE_PERSON_OUTCOME_DELETED),
+ (20, lifecycle_pb2.DELETE_PERSON_OUTCOME_DELETED),
+ ]
+ stored = self.client.stored_person(self.TEAM_ID, "abc-123")
+ assert stored is not None and stored.is_deleted and stored.version == 5
+ assert not self.client.get_person(person_pb2.GetPersonRequest(team_id=self.TEAM_ID, person_id=10)).HasField(
+ "person"
+ )
+ assert not self.client.get_person_by_distinct_id(
+ person_pb2.GetPersonByDistinctIdRequest(team_id=self.TEAM_ID, distinct_id="anon-1")
+ ).HasField("person")
+ assert (
+ self.client.check_cohort_membership(
+ cohort_pb2.CheckCohortMembershipRequest(person_id=10, cohort_ids=[7])
+ ).memberships
+ == []
+ )
+ # The saga leaves no publish-queue row; ClickHouse hears about the delete from the changelog.
+ assert self.client.tombstone_queue == {}
+
+ def test_already_tombstoned_and_held_persons_are_not_touched(self):
+ self._delete([10])
+ self.client.hold_lifecycle_mark(team_id=self.TEAM_ID, person_id=20)
+
+ response = self._delete([10, 20], op_id=self.OP_B)
+
+ assert [r.outcome for r in response.results] == [
+ lifecycle_pb2.DELETE_PERSON_OUTCOME_NOT_FOUND,
+ lifecycle_pb2.DELETE_PERSON_OUTCOME_SKIPPED_CONFLICT,
+ ]
+ stored = self.client.stored_person(self.TEAM_ID, "abc-123")
+ assert stored is not None and stored.version == 5
+ assert self.client.get_person(person_pb2.GetPersonRequest(team_id=self.TEAM_ID, person_id=20)).HasField(
+ "person"
+ )
+
+ def test_retry_with_the_same_op_id_and_request_returns_the_recorded_outcome(self):
+ first = self._delete([10, 20])
+
+ retry = self._delete([10, 20])
+
+ assert retry == first
+ stored = self.client.stored_person(self.TEAM_ID, "abc-123")
+ assert stored is not None and stored.version == 5
+ assert len(self.client.assert_called("lifecycle.delete_persons")) == 2
+
+ @parameterized.expand(
+ [
+ ("different_ids", [10], TEAM_ID),
+ ("different_order", [20, 10], TEAM_ID),
+ ("different_team", [10, 20], 2),
+ ]
+ )
+ def test_same_op_id_with_a_different_request_is_a_definitive_refusal(
+ self, _name: str, person_ids: list[int], team_id: int
+ ):
+ self._delete([10, 20])
+
+ with pytest.raises(grpc.RpcError) as raised:
+ self._delete(person_ids, team_id=team_id)
+
+ assert raised.value.code() == grpc.StatusCode.FAILED_PRECONDITION
+ assert semantic_refusal_reason(raised.value) == "op_id_reused"
+
+ @parameterized.expand(
+ [
+ ("empty", [], OP_A, TEAM_ID),
+ ("over_the_cap", list(range(1, 252)), OP_A, TEAM_ID),
+ ("non_positive_id", [10, 0], OP_A, TEAM_ID),
+ ("malformed_op_id", [10], "not-a-uuid", TEAM_ID),
+ ("team_id_out_of_range", [10], OP_A, 2**31),
+ ]
+ )
+ def test_rejects_requests_the_server_would_reject(
+ self, _name: str, person_ids: list[int], op_id: str, team_id: int
+ ):
+ with pytest.raises(grpc.RpcError) as raised:
+ self._delete(person_ids, op_id=op_id, team_id=team_id)
+
+ assert raised.value.code() == grpc.StatusCode.INVALID_ARGUMENT
+ stored = self.client.stored_person(self.TEAM_ID, "abc-123")
+ assert stored is not None and not stored.is_deleted
diff --git a/posthog/personhog_client/test_metrics_interceptor.py b/posthog/personhog_client/test_metrics_interceptor.py
index 393484dfc95d..f3754e6bd2cf 100644
--- a/posthog/personhog_client/test_metrics_interceptor.py
+++ b/posthog/personhog_client/test_metrics_interceptor.py
@@ -6,7 +6,7 @@ from unittest.mock import MagicMock, patch
import grpc
from parameterized import parameterized
-from posthog.personhog_client.interceptor import MetricsInterceptor, _MutableClientCallDetails
+from posthog.personhog_client.interceptor import MetricsInterceptor, _method_name, _MutableClientCallDetails
def _make_call_details(
@@ -123,3 +123,18 @@ class TestMetricsInterceptorErrorTracking:
interceptor.intercept_unary_unary(lambda d, r: _make_ok_response(), details, request=b"")
mock_errors_counter.labels.return_value.inc.assert_not_called()
+
+
+class TestMethodLabel:
+ @parameterized.expand(
+ [
+ ("facade_keeps_the_bare_name", "/personhog.service.v1.PersonHogService/DeletePersons", "DeletePersons"),
+ (
+ "lifecycle_carries_its_service",
+ "/personhog.lifecycle.v1.PersonHogLifecycle/DeletePersons",
+ "PersonHogLifecycle/DeletePersons",
+ ),
+ ]
+ )
+ def test_services_that_share_a_method_name_get_distinct_labels(self, _name: str, method: str, label: str):
+ assert _method_name(_make_call_details(method=method)) == label
diff --git a/posthog/personhog_client/test_retry_interceptor.py b/posthog/personhog_client/test_retry_interceptor.py
index eeb19ed6da9a..24526c1e7182 100644
--- a/posthog/personhog_client/test_retry_interceptor.py
+++ b/posthog/personhog_client/test_retry_interceptor.py
@@ -18,6 +18,7 @@ from posthog.personhog_client.interceptor import (
RetryInterceptor,
_MutableClientCallDetails,
is_transient_rpc_error,
+ semantic_refusal_reason,
)
from posthog.personhog_client.proto import GetPersonRequest, GetPersonResponse
@@ -372,3 +373,34 @@ class TestIsTransientRpcError:
)
def test_classifies_transport_failures(self, _name: str, exc: BaseException, codes, expected: bool):
assert is_transient_rpc_error(exc, codes=codes) is expected
+
+
+_REFUSAL_TRAILER = (("x-semantic-refusal", "op_id_reused"),)
+
+
+class TestSemanticRefusalReason:
+ @parameterized.expand(
+ [
+ (
+ "refusal",
+ _make_rpc_error(grpc.StatusCode.FAILED_PRECONDITION, trailing_metadata=_REFUSAL_TRAILER),
+ "op_id_reused",
+ ),
+ ("bare_failed_precondition", _make_rpc_error(grpc.StatusCode.FAILED_PRECONDITION), None),
+ (
+ "trailer_on_another_code",
+ _make_rpc_error(grpc.StatusCode.UNAVAILABLE, trailing_metadata=_REFUSAL_TRAILER),
+ None,
+ ),
+ (
+ "wrapped_refusal",
+ _wrapped_in_database_error(
+ _make_rpc_error(grpc.StatusCode.FAILED_PRECONDITION, trailing_metadata=_REFUSAL_TRAILER)
+ ),
+ "op_id_reused",
+ ),
+ ("not_an_rpc_error", ValueError("boom"), None),
+ ]
+ )
+ def test_reads_the_refusal_slug(self, _name: str, exc: BaseException, expected: str | None):
+ assert semantic_refusal_reason(exc) == expected
diff --git a/posthog/settings/personhog.py b/posthog/settings/personhog.py
index 579b217ca6dd..8672900ee2aa 100644
--- a/posthog/settings/personhog.py
+++ b/posthog/settings/personhog.py
@@ -3,6 +3,12 @@ from posthog.settings.utils import get_from_env, str_to_bool
PERSONHOG_ADDR = get_from_env("PERSONHOG_ADDR", "")
PERSONHOG_TIMEOUT_MS = get_from_env("PERSONHOG_TIMEOUT_MS", 5000, type_cast=int)
+# A router with the identity proxy enabled; empty means the lifecycle path is unavailable here.
+PERSONHOG_LIFECYCLE_ADDR = get_from_env("PERSONHOG_LIFECYCLE_ADDR", "")
+# Above the identity server's own execute timeout (30 s by default), after which it answers
+# UNAVAILABLE itself; a shorter client deadline would abandon calls the server was about to answer.
+PERSONHOG_LIFECYCLE_TIMEOUT_MS = get_from_env("PERSONHOG_LIFECYCLE_TIMEOUT_MS", 45_000, type_cast=int)
+
# gRPC channel options
PERSONHOG_KEEPALIVE_TIME_MS = get_from_env("PERSONHOG_KEEPALIVE_TIME_MS", 30_000, type_cast=int)
PERSONHOG_KEEPALIVE_TIMEOUT_MS = get_from_env("PERSONHOG_KEEPALIVE_TIMEOUT_MS", 5_000, type_cast=int)