feat: add If-Match support and fix stack ETag synchronization

[desperateCoder]

• Implement Optimistic Concurrency Control via If-Match header for Boards, Stacks, Cards, and Labels.
• Fix ETag propagation when renaming or reordering stacks (Fixes Update stack / list: ETag not updated #2866).
• Ensure automatic last_modified updates in BoardMapper and StackMapper.
• Add unit and integration tests for OCC and ETag logic.

Fixes #2866

• Resolves: Update stack / list: ETag not updated #2866
• Target version: main

Summary

Implementation of If-Match support and ETag synchronization fixes

This pull request introduces support for the HTTP If-Match header to enable Optimistic Concurrency Control (OCC) and resolves several issues related to ETag propagation, specifically when updating lists (stacks).

1. Support for If-Match (Optimistic Concurrency Control)

• Goal: Prevent clients from accidentally overwriting changes if a resource has been modified between the time it was fetched and the time an update was submitted.
• Changes:
  • Added PreconditionFailedException which returns HTTP 412 status code.
  • Enhanced ChangeHelper with a checkIfMatch method. It validates the client-provided ETag against the server-side state (prioritizing cache with a database fallback).
  • Added support for the If-Match: * wildcard.
  • Integrated the check into all relevant PUT and DELETE endpoints for Boards, Stacks, Cards, and Labels.
  • Updated controller get and index methods to return the more precise ETag from the cache when available.

2. ETag Synchronization Fixes (Fixes #861)

• Issue: Renaming a list (stack) did not reliably update the ETag of the list or the board (see Update stack / list: ETag not updated #2866). Consequently, mobile clients (like the Android app) would not see name changes until a card within that list was modified.
• Changes:
  • Mapper Automation: BoardMapper and StackMapper now automatically update the last_modified timestamp on every insert and update operation.
  • ETag Propagation: Corrected and expanded ChangeHelper->stackChanged. It now updates the stack-specific ETag and automatically triggers a parent board update via boardChanged.
  • Service Integration: Updated StackService to ensure all modifying operations (update, reorder, setDoneStack) use the new ETag invalidation logic.
  • Card Updates: Optimized cardChanged propagation to avoid redundant database writes to the board while still ensuring ETag invalidation for the card, stack, and board.

3. Refactoring and Consistency

• Labels: Integrated labels into the ETag cache logic. Label modifications now correctly invalidate relevant cache states.
• ChangeHelper: Fixed type constant errors (e.g., the incorrect use of TYPE_CARD for stack operations).

4. Quality Assurance

• Unit Tests:
  • Created tests/unit/Db/ChangeHelperTest.php to test the If-Match logic in isolation.
  • Updated controller tests (BoardApiControllerTest, CardApiControllerTest, StackApiControllerTest, LabelApiControllerTest) to mock the new ChangeHelper dependency and verify ETag handling.
• Integration Tests:
  • Added scenarios to tests/integration/features/api/boards.feature for successful and failing If-Match requests.
  • Extended DeckApiContext to support API requests that include both custom headers and a JSON body.

5. Disclaimer

• if anything needs to be reworked, please tell me so
• i did my best running the tests, but i don't have the full development environment, so please tell me if something is off or misbehaves in the real env

TODO

• ...

Checklist

• Code is properly formatted
• Sign-off message is added to all commits
• Tests (unit, integration, api and/or acceptance) are included
• Documentation (manuals or wiki) has been updated or is not required