Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions pydgraph/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@
from pydgraph.client_stub import DgraphClientStub, client_stub
from pydgraph.errors import (
AbortedError,
AbortReason,
ConnectionError, # noqa: A004
RetriableError,
TransactionError,
Expand Down Expand Up @@ -44,6 +45,7 @@
from pydgraph.txn import Txn

__all__ = [
"AbortReason",
"AbortedError",
"AsyncDgraphClient",
"AsyncDgraphClientStub",
Expand Down
4 changes: 2 additions & 2 deletions pydgraph/async_txn.py
Original file line number Diff line number Diff line change
Expand Up @@ -341,7 +341,7 @@ def _common_except_mutate(error: Exception) -> NoReturn:
The original error otherwise
"""
if util.is_aborted_error(error):
raise errors.AbortedError
raise errors.AbortedError(util.abort_error_message(error))

if util.is_retriable_error(error):
raise errors.RetriableError(error)
Expand Down Expand Up @@ -437,7 +437,7 @@ def _common_except_commit(error: Exception) -> NoReturn:
The original error otherwise
"""
if util.is_aborted_error(error):
raise errors.AbortedError
raise errors.AbortedError(util.abort_error_message(error))

raise error

Expand Down
76 changes: 74 additions & 2 deletions pydgraph/errors.py
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,8 @@

from __future__ import annotations

import enum

from pydgraph.meta import VERSION

__author__ = "Garvit Pahal"
Expand All @@ -13,13 +15,83 @@
__status__ = "development"


class AbortReason(enum.Enum):
"""The category of a transaction abort, as reported by the Dgraph server.

The server encodes the reason as a ``"<code>: <detail>"`` prefix on the gRPC
ABORTED status message; :func:`parse_abort_reason` maps that prefix to one of
these values.

- ``CONFLICT`` — a write-write conflict with another concurrent transaction;
retrying with a fresh transaction is the expected response. The server cannot
say *which* key collided: conflict keys are one-way fingerprints by the time
they are compared, so the culprit may be the data key written directly, or an
index or count key derived from it. On an ``@upsert`` predicate the uid is
excluded from the comparison, so any two transactions writing the same value
conflict.
- ``PREDICATE_MOVE`` — a predicate is being moved between groups and commits on
it are blocked, or it finished moving while the transaction was open; back off
and retry once the move completes.
- ``STALE_STARTTS`` — the transaction's start timestamp is older than the oldest
timestamp the server can still validate against. That happens after a Zero
leader change, and also when Zero trims its conflict map at a snapshot, which
is not a leader change at all. Retry with a fresh transaction.
- ``UNKNOWN`` — no category was reported. This covers aborts from older servers,
which do not categorize at all, and aborts a current server declines to
categorize because no published category fits — for example a transaction
already aborted out of band by a schema change or the idle-transaction reaper,
a cancelled request, or a predicate no group currently serves. The message
still explains what happened; only the machine-readable category is absent.

Categories are matched on the message prefix, and an unrecognized prefix degrades
to ``UNKNOWN``. A newer server may therefore introduce categories this enum does
not name without breaking this client.
"""

CONFLICT = "conflict"
PREDICATE_MOVE = "predicate-move"
STALE_STARTTS = "stale-startts"
UNKNOWN = "unknown"


def parse_abort_reason(message: str | None) -> AbortReason:
"""Parses the abort category from a server abort message.

The reason is the ``"<code>: <detail>"`` prefix; matching is case-insensitive and
tolerant of surrounding whitespace. Only the *first* colon delimits the category —
several server messages contain colons of their own in the detail that follows.

A message with no recognized prefix returns :attr:`AbortReason.UNKNOWN`. That is
the expected result both for a pre-feature server and for causes a current server
deliberately leaves uncategorized rather than implying the wrong remedy.
"""
if not message:
return AbortReason.UNKNOWN
code = message.split(":", 1)[0].strip().lower()
for reason in (
AbortReason.CONFLICT,
AbortReason.PREDICATE_MOVE,
AbortReason.STALE_STARTTS,
):
if code == reason.value:
return reason
return AbortReason.UNKNOWN


class AbortedError(Exception):
"""Error thrown by aborted transactions."""
"""Error thrown by aborted transactions.

The parsed abort category is available as :attr:`reason`; the full server message
remains available via ``str(error)``.
"""

def __init__(
self, message: str = "Transaction has been aborted. Please retry"
self,
message: str = "Transaction has been aborted. Please retry",
reason: AbortReason | None = None,
) -> None:
super().__init__(message)
self.reason = reason if reason is not None else parse_abort_reason(message)


class RetriableError(Exception):
Expand Down
4 changes: 2 additions & 2 deletions pydgraph/txn.py
Original file line number Diff line number Diff line change
Expand Up @@ -339,7 +339,7 @@ def create_request(
@staticmethod
def _common_except_mutate(error: Exception) -> None:
if util.is_aborted_error(error):
raise errors.AbortedError
raise errors.AbortedError(util.abort_error_message(error))

if util.is_retriable_error(error):
raise errors.RetriableError(error)
Expand Down Expand Up @@ -399,7 +399,7 @@ def _common_commit(self) -> bool:
@staticmethod
def _common_except_commit(error: Exception) -> None:
if util.is_aborted_error(error):
raise errors.AbortedError
raise errors.AbortedError(util.abort_error_message(error))

raise error

Expand Down
14 changes: 14 additions & 0 deletions pydgraph/util.py
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,20 @@ def is_aborted_error(error: Any) -> bool:
return False


def abort_error_message(error: Any) -> str:
"""Returns the server-supplied message from a gRPC error.

Prefers ``error.details()`` (the status description, which carries the abort
reason prefix), falling back to ``str(error)``. Used to surface the categorized
abort reason on AbortedError.
"""
if hasattr(error, "details") and callable(error.details):
details = error.details()
if details:
return details
return str(error)


def is_retriable_error(error: Exception) -> bool:
"""Returns true if the error is retriable (e.g server is not ready yet)."""
msg = str(error)
Expand Down
36 changes: 36 additions & 0 deletions tests/docker-compose.multigroup.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
# Multi-group, no-ACL cluster for the live transaction-abort-reason tests
# (tests/test_abort_reason_live.py). Two alpha groups (replicas=1) enable the
# predicate-move case; the single zero is restartable for the stale-startts case.
#
# Usage:
# DGRAPH_IMAGE_TAG=local docker compose -f tests/docker-compose.multigroup.yml up -d
# TEST_SERVER_ADDR=localhost:9180 \
# TEST_ZERO_HTTP=localhost:6180 \
# TEST_ZERO_RESTART_CMD="docker compose -f tests/docker-compose.multigroup.yml restart zero1" \
# python -m pytest tests/test_abort_reason_live.py -v
# docker compose -f tests/docker-compose.multigroup.yml down
services:
zero1:
image: dgraph/dgraph:${DGRAPH_IMAGE_TAG:-latest}
ports:
- "5180:5180"
- "6180:6180"
command: dgraph zero -o 100 --my=zero1:5180 --replicas=1 --logtostderr -v=2 --bindall

alpha1:
image: dgraph/dgraph:${DGRAPH_IMAGE_TAG:-latest}
ports:
- "8180:8180"
- "9180:9180"
command:
dgraph alpha -o 100 --my=alpha1:7180 --zero=zero1:5180 --logtostderr -v=2 --raft "idx=1;
group=1" --security "whitelist=0.0.0.0/0;"

alpha2:
image: dgraph/dgraph:${DGRAPH_IMAGE_TAG:-latest}
ports:
- "8182:8182"
- "9182:9182"
command:
dgraph alpha -o 102 --my=alpha2:7182 --zero=zero1:5180 --logtostderr -v=2 --raft "idx=2;
group=2" --security "whitelist=0.0.0.0/0;"
172 changes: 172 additions & 0 deletions tests/test_abort_reason.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,172 @@
# SPDX-FileCopyrightText: © 2017-2026 Istari Digital, Inc.
# SPDX-License-Identifier: Apache-2.0

"""Unit tests for surfacing the transaction-abort reason on AbortedError.

The Dgraph server encodes the abort category as a ``"<code>: <detail>"`` prefix on the
gRPC ABORTED status message. These tests verify that the prefix is parsed into an
``AbortReason``, that the full message is preserved, and that aborts from a server which
reports no reason degrade gracefully to ``UNKNOWN``.
"""

from __future__ import annotations

import unittest

import pydgraph
from pydgraph import errors

# Verbatim messages the server sends, from the abort-detail constants in
# dgraph/cmd/zero/oracle.go. Kept literal rather than abbreviated so these fixtures stay
# a faithful record of the wire format: several now contain colons of their own after the
# category prefix, which is exactly the case the parser has to get right.
SERVER_CONFLICT = (
"conflict: Transaction has been aborted. Please retry. Another transaction "
"committed to one of the same keys. The conflicting key cannot be identified: it "
"may be the data key written directly, or an index or count key derived from it. "
"On an @upsert predicate the uid is excluded, so any two transactions writing the "
"same value conflict"
)
SERVER_STALE_STARTTS = (
"stale-startts: Transaction start timestamp is older than the oldest timestamp Zero "
"can still validate (Zero leader change, or its conflict map was trimmed at a "
"snapshot). Please retry"
)
SERVER_MOVE_IN_FLIGHT = (
"predicate-move: Commits on predicate name are blocked due to predicate move"
)
SERVER_MOVE_COMPLETED = (
"predicate-move: Mutation done in group: 1. Predicate name assigned to 2"
)

# Causes the server deliberately leaves uncategorized: it says what happened, but no
# published category fits, so it sends the detail with no prefix rather than implying a
# wrong remedy.
SERVER_PRE_ABORTED = (
"Transaction has been aborted. Please retry. It was already aborted before this "
"commit was decided, which happens when a schema update or a drop-predicate cancels "
"pending transactions on a predicate it touched, or when the server ages out "
'transactions idle for longer than --limit "txn-abort-after"'
)
SERVER_TABLET_NIL = "Tablet for name is nil"
SERVER_MALFORMED_KEY = "Unable to find group id in 1name"
SERVER_BAD_GROUP_ID = (
'unable to parse group id from xname: strconv.Atoi: parsing "x": invalid syntax'
)
SERVER_CTX_CANCELLED = "context canceled"


class TestAbortReason(unittest.TestCase):
# --- The three server-reported categories ---

def test_conflict_reason(self) -> None:
err = errors.AbortedError(SERVER_CONFLICT)
assert err.reason == pydgraph.AbortReason.CONFLICT

def test_predicate_move_reason(self) -> None:
err = errors.AbortedError(SERVER_MOVE_IN_FLIGHT)
assert err.reason == pydgraph.AbortReason.PREDICATE_MOVE

def test_stale_startts_reason(self) -> None:
err = errors.AbortedError(SERVER_STALE_STARTTS)
assert err.reason == pydgraph.AbortReason.STALE_STARTTS

# --- Only the first colon delimits the category ---

def test_categories_parse_despite_embedded_colons(self) -> None:
# The conflict detail contains "cannot be identified: it may be", and the
# completed-move detail contains "group: 1". Splitting on the wrong colon would
# misread both.
assert SERVER_CONFLICT.count(":") > 1, "fixture must have >1 colon to be useful"
assert SERVER_MOVE_COMPLETED.count(":") > 1

assert (
errors.AbortedError(SERVER_CONFLICT).reason == pydgraph.AbortReason.CONFLICT
)
assert (
errors.AbortedError(SERVER_MOVE_COMPLETED).reason
== pydgraph.AbortReason.PREDICATE_MOVE
)

# --- Full message preserved alongside the parsed reason ---

def test_full_message_preserved(self) -> None:
err = errors.AbortedError(SERVER_CONFLICT)
# The complete human-readable message survives, including the detail explaining
# which kinds of key could have collided.
assert str(err) == SERVER_CONFLICT

# --- Graceful degradation when no category is reported ---

def test_legacy_message_degrades_to_unknown(self) -> None:
# The default message (what pre-feature servers emit) has no category prefix.
err = errors.AbortedError()
assert err.reason == pydgraph.AbortReason.UNKNOWN

def test_unrecognized_prefix_degrades_to_unknown(self) -> None:
err = errors.AbortedError("something-else: not a known category")
assert err.reason == pydgraph.AbortReason.UNKNOWN

def test_uncategorized_server_causes_degrade_to_unknown(self) -> None:
# A current server also sends aborts with no category, for causes no published
# category fits. The message still explains what happened; only the
# machine-readable code is absent. These are the real messages, not invented.
for message in (
SERVER_PRE_ABORTED,
SERVER_TABLET_NIL,
SERVER_MALFORMED_KEY,
SERVER_BAD_GROUP_ID,
SERVER_CTX_CANCELLED,
):
err = errors.AbortedError(message)
assert err.reason == pydgraph.AbortReason.UNKNOWN, message
assert str(err) == message, "the explanation must survive intact"

def test_uncategorized_lookalikes_are_not_misparsed(self) -> None:
# The out-of-band abort opens with the exact sentence a pre-feature server sent
# for every abort, and the malformed-group-id message carries a colon of its own.
# Neither may be mistaken for a category: a false CONFLICT would tell a caller to
# retry something that cannot succeed.
assert SERVER_PRE_ABORTED.startswith(
"Transaction has been aborted. Please retry"
)
assert (
errors.AbortedError(SERVER_PRE_ABORTED).reason
== pydgraph.AbortReason.UNKNOWN
)

assert ":" in SERVER_BAD_GROUP_ID
assert (
errors.AbortedError(SERVER_BAD_GROUP_ID).reason
== pydgraph.AbortReason.UNKNOWN
)

# --- Parsing robustness ---

def test_reason_is_case_insensitive_and_trimmed(self) -> None:
assert (
errors.AbortedError("CONFLICT: x").reason == pydgraph.AbortReason.CONFLICT
)
assert (
errors.AbortedError(" predicate-move : y").reason
== pydgraph.AbortReason.PREDICATE_MOVE
)

def test_reason_without_detail_still_parses(self) -> None:
assert errors.AbortedError("conflict").reason == pydgraph.AbortReason.CONFLICT

def test_parse_abort_reason_none_is_unknown(self) -> None:
assert errors.parse_abort_reason(None) == pydgraph.AbortReason.UNKNOWN
assert errors.parse_abort_reason("") == pydgraph.AbortReason.UNKNOWN

# --- Explicit reason overrides parsing ---

def test_explicit_reason_overrides_message(self) -> None:
err = errors.AbortedError(
"opaque message", reason=pydgraph.AbortReason.STALE_STARTTS
)
assert err.reason == pydgraph.AbortReason.STALE_STARTTS


if __name__ == "__main__":
unittest.main()
Loading