Skip to content

Release v3.0.0

Latest

Choose a tag to compare

@github-actions github-actions released this 15 Nov 02:48

v3.0.0

Changelog

Target 3.0.0: the connection is repaired (rolled back, closed only when that fails) after any failure, nested calls
and leftover transactions are no longer retried, retry() clears the entity manager before a replay, backoff is
jittered, DBAL 4 / ORM 3 are required. See UPGRADING.

Fixed

  • Nested deadlocks on MySQL / MariaDB no longer surface as 1305 or poison the worker's connection. A deadlock
    (1213) inside a nested transaction drops every savepoint; the ORM's ROLLBACK TO SAVEPOINT then fails with 1305,
    and 2.x's blind EntityManager::rollback() before the retry failed with 1305 again and escaped. The connection
    stayed at nesting level 2, so the next request ran inside a ghost savepoint (its writes committed immediately).
    After any failure the service now rolls back the levels the operation left open and closes the connection only
    when that rollback fails (Connection::close() resets the nesting level). Ordinary failures keep session state
    (variables, GET_LOCK, advisory locks). Covered by real MySQL 8.4 / MariaDB 11.4 tests.
  • Inside a caller's transaction a transient failure is no longer retried. The old rollback undid the caller's own
    transaction and replayed only the inner operation in auto-commit (PostgreSQL), or failed with 1305 (MySQL).
  • retry() clears an open entity manager before replaying: a raw DBAL failure left the failed attempt's entities
    scheduled, and the replay inserted them twice (QA-DDRB-M2).
  • rollback_on_deadlock: false never replays on a connection the failure left in a transaction (QA-DDRB-M3).
  • A 1305 lost savepoint is transient only through the deadlock in its chain: after an implicit commit (DDL inside the
    transaction) it was retried and the committed work replayed (QA-DDRB-M1).
  • Connections with auto-commit disabled are retried at their implicit transaction level (QA-DDRB-L1).

Added

  • Detection of transient failures: DBAL RetryableException, MySQL / MariaDB 1213, 1205, MariaDB 1020,
    SQLSTATE 40001 / 40P01 / 55P03 (Failure\TransientFailureClassifier, Failure\TransientFailureKind).
    Profile option retry_lock_wait_timeout (default false) and time budget max_total_ms (default none).
  • Exponential backoff with full jitter: profile options backoff_base_ms (default 100), backoff_max_ms (default
    2000) and jitter (full | none). sleep_ms stays as an alias of backoff_base_ms.
  • Worker guard (opt-in, worker_guard.enabled): on kernel.request (main request, priority 2048) and
    kernel.terminate (priority -2048) a connection left in a transaction is rolled back (one level) or closed
    (deeper, or a failed rollback); closed entity managers are reset; open ones are cleared on terminate
    (clear_managers). With messenger (default on) the same runs after every Messenger message: on a failed message
    the connections are repaired at priority 512, before SendFailedMessageForRetryListener writes the retry envelope,
    and managers are cleared at -2048. Only connections and managers the container already initialised are touched.
    One warning per repair, without SQL.
  • HTTP mapping (opt-in, http_mapping.enabled): a kernel.exception listener (priority -64) maps transient
    failures (and Nowo\TransactionContract\TransientStorageFailure) to 503 with Retry-After
    (retry_after_seconds, or the exception's hint), and conflict_exceptions (default OptimisticLockException,
    UniqueConstraintViolationException, not when they wrap a driver error such as "Commit failed") to 409. Scoped by
    paths (segment boundaries) / routes prefixes or global; format: exception keeps the host's own rendering,
    format: problem_json answers RFC 9457 directly; the client never sees SQL.
  • nowo-tech/transaction-contract adapter: Transaction\DeadlockRetryTransactionRunner implements
    TransactionRunnerInterface (service id nowo_doctrine_deadlock_retry.transaction_runner): wrapInTransaction()
    through retry(), transient failures rethrown as TransientStorageFailure with retry_after_seconds; option
    transaction_runner.profile. The interface is aliased to it only when nothing defines it (compiler pass, priority
    10, so it wins over bundles' one-attempt defaults that follow the recipe; a host's own alias always wins). A
    TransientStorageFailure from a nested runner is classified by the storage error it carries. New requirement
    nowo-tech/transaction-contract ^1.0.
  • Connection\ConnectionRepairer, a public service for bundles that clean up after a failed unit of work.
  • Optional PSR-3 logger on DeadlockRetryService: retries at info, repairs at notice, never SQL.

Changed

  • Requires doctrine/dbal ^4.0 and doctrine/orm ^3.0 (DBAL 3 / ORM 2 were never tested).
  • When the service gives up on a transient failure that only Doctrine wrapped, it rethrows the transient exception
    itself (the DeadlockException, not the ORM's 1305 DriverException).
  • retry() always makes at least one attempt (a negative max_retries on a hand-built RetryProfile used to throw).
  • The internal "Deadlock retry loop ended without result" RuntimeException is gone.

Documentation

  • USAGE: "High-load readiness" (what goes wrong, worker guard, HTTP mapping, standard Symfony and DDD host examples,
    migration guide for bundles with their own reset helpers); "Behaviour on transient failures" replaces "Behaviour on
    deadlock". CONFIGURATION: new profile, worker_guard and http_mapping options.

Documentation

  • USAGE: "Using it from a DDD / hexagonal application" with a standard Symfony host section and a DDD / hexagonal
    host section (own TransactionRunner port, adapter on DeadlockRetryInterface, events after commit), and a
    statement that the bundle never flushes or commits on its own (REQ-ARCH-001).

Tests

  • Real-database suite (tests/Database, make test-db, CI job "Real databases"): two sessions cause a real deadlock
    in a nested flush on MySQL 8.4 and MariaDB 11.4 (clean retry, nesting level 0, next request commits), a real lock
    wait timeout (retried; exhausted → 503 + Retry-After), the worker guard repairing a poisoned connection and
    clearing pending changes, a PostgreSQL 16 serialization failure (40001) and lock timeout (55P03), a MariaDB 11.8
    snapshot conflict (1020), the Messenger repair before the retry envelope, the max_total_ms bound (budget plus
    one attempt), and the QA audit regressions (implicit commit not retried, dirty manager cleared, no
    replay on a leftover transaction, auto-commit off retried, session locks kept after a domain failure).
  • DDD host case: plain-PHP aggregate, host TransactionRunner port and an adapter on the container's
    DeadlockRetryInterface alias; a deadlock closes the manager, the unit of work is replayed on the reset manager and
    the domain event is published once, after commit.

What's Changed

  • docs(arch): DDD / hexagonal host section and DDD host test (REQ-ARCH-001) by @HecFranco in #68
  • feat!: load readiness: connection repair, jittered backoff, worker guard and HTTP mapping by @HecFranco in #69

Full Changelog: v2.4.0...v3.0.0