Compare commits

...
Author SHA1 Message Date
Andrew BeveridgeandClaude Opus 4.6 cfeb30819e Merge main, resolve version conflict (0.119.5)
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-26 14:53:00 -05:00
Andrew BeveridgeandClaude Opus 4.6 85af3c08d5 Fix brand code race condition with Firestore atomic counter
Two concurrent jobs received the same brand code (NOMADNP-0012) because
get_next_brand_code() scanned Dropbox folders to determine the next
number — a TOCTOU race condition. Replace with BrandCodeService that
uses Firestore transactions for atomic allocation. Counter initializes
from Dropbox on first use, then allocates atomically. E2E cleanup
recycles brand codes for reuse. Adds input validation for recycled
numbers.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-26 14:45:21 -05:00
9 changed files with 853 additions and 20 deletions

No files matched your search

+12
View File
@@ -1668,6 +1668,18 @@ async def cleanup_distribution(
"status": "success" if success else "failed",
"path": full_path
}
# Recycle the brand code number so it can be reused
if success:
try:
from backend.services.brand_code_service import (
BrandCodeService, get_brand_code_service
)
prefix, number = BrandCodeService.parse_brand_code(brand_code)
get_brand_code_service().recycle_brand_code(prefix, number)
results["dropbox"]["recycled_brand_code"] = True
except (ValueError, Exception) as e:
logger.warning(f"Failed to recycle brand code {brand_code}: {e}")
results["dropbox"]["recycled_brand_code"] = False
else:
results["dropbox"] = {"status": "failed", "reason": "Dropbox credentials not configured"}
except Exception as e:
+225
View File
@@ -0,0 +1,225 @@
"""
Brand code allocation service using Firestore atomic counters.
Replaces the previous Dropbox folder-scanning approach which was susceptible to
TOCTOU race conditions when concurrent jobs read the same folder state.
Uses Firestore transactions to atomically allocate unique brand codes.
Supports recycling numbers when E2E cleanup deletes test brand codes.
"""
import logging
import re
from datetime import datetime, timezone
from typing import Optional
from google.cloud import firestore
from backend.config import settings
logger = logging.getLogger(__name__)
BRAND_CODE_COUNTERS_COLLECTION = "brand_code_counters"
# Singleton instance
_brand_code_service: Optional["BrandCodeService"] = None
class BrandCodeService:
"""Atomic brand code allocation using Firestore counters."""
def __init__(self, db: Optional[firestore.Client] = None):
if db is None:
self.db = firestore.Client(project=settings.google_cloud_project)
else:
self.db = db
def allocate_brand_code(self, prefix: str, dropbox_path: str) -> str:
"""
Atomically allocate the next brand code for a given prefix.
Uses a Firestore transaction to ensure no two concurrent callers
receive the same number. If recycled numbers are available (from
E2E cleanup), the smallest recycled number is reused first.
On first use for a prefix, initializes the counter by scanning
Dropbox to find the current max number.
Args:
prefix: Brand prefix (e.g., "NOMAD" or "NOMADNP")
dropbox_path: Dropbox path for one-time initialization scan
Returns:
Brand code string (e.g., "NOMAD-1264")
"""
doc_ref = self.db.collection(BRAND_CODE_COUNTERS_COLLECTION).document(prefix)
@firestore.transactional
def allocate_in_transaction(transaction):
doc = doc_ref.get(transaction=transaction)
if not doc.exists:
# First use — initialize from Dropbox scan
next_number = self._get_initial_next_number(prefix, dropbox_path)
allocated = next_number
transaction.set(doc_ref, {
"prefix": prefix,
"next_number": next_number + 1,
"recycled": [],
"initialized_at": datetime.now(timezone.utc),
"last_updated": datetime.now(timezone.utc),
})
return allocated
data = doc.to_dict()
recycled = data.get("recycled", [])
if recycled:
# Reuse smallest recycled number
recycled.sort()
allocated = recycled.pop(0)
transaction.update(doc_ref, {
"recycled": recycled,
"last_updated": datetime.now(timezone.utc),
})
else:
# Allocate next sequential number
allocated = data["next_number"]
transaction.update(doc_ref, {
"next_number": allocated + 1,
"last_updated": datetime.now(timezone.utc),
})
return allocated
transaction = self.db.transaction()
number = allocate_in_transaction(transaction)
brand_code = f"{prefix}-{number:04d}"
logger.info(f"Allocated brand code: {brand_code}")
return brand_code
def recycle_brand_code(self, prefix: str, number: int) -> None:
"""
Return a brand code number to the recycled pool.
Called when E2E cleanup deletes a brand code's distribution.
The number will be reused on the next allocation for this prefix.
Args:
prefix: Brand prefix (e.g., "NOMAD")
number: The numeric portion to recycle (e.g., 1234)
"""
doc_ref = self.db.collection(BRAND_CODE_COUNTERS_COLLECTION).document(prefix)
@firestore.transactional
def recycle_in_transaction(transaction):
doc = doc_ref.get(transaction=transaction)
if not doc.exists:
# Counter doesn't exist yet — nothing to recycle into.
# The number will naturally be below next_number when
# the counter is initialized, so it would create a gap.
# Just log and skip.
logger.warning(
f"Cannot recycle {prefix}-{number:04d}: counter doc doesn't exist"
)
return
data = doc.to_dict()
next_number = data.get("next_number", 0)
if number <= 0 or number >= next_number:
logger.warning(
f"Cannot recycle {prefix}-{number:04d}: "
f"invalid (next_number={next_number})"
)
return
recycled = data.get("recycled", [])
if number not in recycled:
recycled.append(number)
transaction.update(doc_ref, {
"recycled": recycled,
"last_updated": datetime.now(timezone.utc),
})
logger.info(f"Recycled brand code number: {prefix}-{number:04d}")
else:
logger.warning(f"Number {number} already in recycled pool for {prefix}")
transaction = self.db.transaction()
recycle_in_transaction(transaction)
def _get_initial_next_number(self, prefix: str, dropbox_path: str) -> int:
"""
Scan Dropbox once to determine the starting next_number.
This is only called when the counter document doesn't exist yet
(one-time migration from the old Dropbox-scanning approach).
Args:
prefix: Brand prefix to scan for
dropbox_path: Dropbox path containing organized folders
Returns:
The next number to allocate (max existing + 1, minimum 1)
"""
try:
from backend.services.dropbox_service import get_dropbox_service
dropbox = get_dropbox_service()
if not dropbox.is_configured:
logger.warning(
f"Dropbox not configured for initialization of {prefix} counter, starting at 1"
)
return 1
folders = dropbox.list_folders(dropbox_path)
pattern = re.compile(rf"^{re.escape(prefix)}-(\d{{4}})")
existing_nums: set[int] = set()
for folder in folders:
match = pattern.match(folder)
if match:
existing_nums.add(int(match.group(1)))
if existing_nums:
next_num = max(existing_nums) + 1
logger.info(
f"Initialized {prefix} counter from Dropbox: "
f"max existing={max(existing_nums)}, next_number={next_num}"
)
return next_num
logger.info(f"No existing {prefix} codes found in Dropbox, starting at 1")
return 1
except Exception as e:
logger.error(f"Failed to initialize {prefix} counter from Dropbox: {e}")
raise
@staticmethod
def parse_brand_code(brand_code: str) -> tuple[str, int]:
"""
Parse a brand code string into prefix and number.
Args:
brand_code: e.g., "NOMAD-1234" or "NOMADNP-0012"
Returns:
Tuple of (prefix, number), e.g., ("NOMAD", 1234)
Raises:
ValueError: If brand_code doesn't match expected format
"""
match = re.match(r"^([A-Z]+)-(\d+)$", brand_code)
if not match:
raise ValueError(f"Invalid brand code format: {brand_code}")
return match.group(1), int(match.group(2))
def get_brand_code_service() -> BrandCodeService:
"""Get or create the singleton BrandCodeService instance."""
global _brand_code_service
if _brand_code_service is None:
_brand_code_service = BrandCodeService()
return _brand_code_service
+4
View File
@@ -111,6 +111,10 @@ class DropboxService:
"""
Calculate next brand code from existing folders, filling gaps in the sequence.
NOTE: This method is only used for one-time initialization of the Firestore
counter (see brand_code_service.py). All runtime brand code allocation now
goes through BrandCodeService.allocate_brand_code() for atomic safety.
Scans the folder for existing brand codes like "NOMAD-0001" and
returns the first available code, filling any gaps left by deleted outputs.
+590
View File
@@ -0,0 +1,590 @@
"""
Tests for BrandCodeService - atomic brand code allocation via Firestore counters.
Tests cover:
- Sequential allocation returns unique codes
- Recycled numbers are reused (smallest first)
- One-time initialization from Dropbox scan
- Both NOMAD and NOMADNP prefixes work independently
- Recycle then allocate round-trip
- parse_brand_code utility
"""
import pytest
from unittest.mock import Mock, MagicMock, patch
from datetime import datetime, timezone
import sys
sys.modules.setdefault('google.cloud.firestore', MagicMock())
sys.modules.setdefault('google.cloud.storage', MagicMock())
def _make_doc_snapshot(exists, data=None):
"""Create a mock Firestore document snapshot."""
doc = Mock()
doc.exists = exists
if data:
doc.to_dict.return_value = data
return doc
def _setup_service_and_mocks(mock_db, doc_snapshot):
"""Common setup: create service with fake transactional decorator."""
mock_doc_ref = Mock()
mock_db.collection.return_value.document.return_value = mock_doc_ref
mock_doc_ref.get.return_value = doc_snapshot
mock_transaction = Mock()
mock_db.transaction.return_value = mock_transaction
return mock_doc_ref, mock_transaction
class TestBrandCodeServiceAllocate:
"""Test allocate_brand_code method."""
@pytest.fixture
def mock_db(self):
return MagicMock()
def test_allocate_sequential_number(self, mock_db):
"""Test allocation returns next sequential number when no recycled numbers."""
doc_snapshot = _make_doc_snapshot(True, {
"prefix": "NOMAD",
"next_number": 1264,
"recycled": [],
})
mock_doc_ref, mock_transaction = _setup_service_and_mocks(mock_db, doc_snapshot)
with patch('backend.services.brand_code_service.firestore') as mock_fs, \
patch('backend.services.brand_code_service.settings') as mock_settings:
mock_settings.google_cloud_project = 'test-project'
def fake_transactional(func):
def wrapper(transaction, *args, **kwargs):
return func(transaction, *args, **kwargs)
return wrapper
mock_fs.transactional = fake_transactional
from backend.services.brand_code_service import BrandCodeService
svc = BrandCodeService(db=mock_db)
result = svc.allocate_brand_code("NOMAD", "/Karaoke/Tracks-Organized")
assert result == "NOMAD-1264"
# Transaction.update should have been called to increment next_number
mock_transaction.update.assert_called_once()
update_args = mock_transaction.update.call_args[0]
assert update_args[0] is mock_doc_ref # first arg is doc_ref
assert update_args[1]["next_number"] == 1265
def test_allocate_uses_recycled_number(self, mock_db):
"""Test allocation pops smallest recycled number first."""
doc_snapshot = _make_doc_snapshot(True, {
"prefix": "NOMAD",
"next_number": 1264,
"recycled": [1250, 1230, 1245],
})
mock_doc_ref, mock_transaction = _setup_service_and_mocks(mock_db, doc_snapshot)
with patch('backend.services.brand_code_service.firestore') as mock_fs, \
patch('backend.services.brand_code_service.settings') as mock_settings:
mock_settings.google_cloud_project = 'test-project'
def fake_transactional(func):
def wrapper(transaction, *args, **kwargs):
return func(transaction, *args, **kwargs)
return wrapper
mock_fs.transactional = fake_transactional
from backend.services.brand_code_service import BrandCodeService
svc = BrandCodeService(db=mock_db)
result = svc.allocate_brand_code("NOMAD", "/path")
assert result == "NOMAD-1230"
# Verify recycled list was updated (1230 removed, sorted remainder)
update_args = mock_transaction.update.call_args[0][1]
assert update_args["recycled"] == [1245, 1250]
def test_allocate_initializes_from_dropbox_when_no_counter(self, mock_db):
"""Test first allocation scans Dropbox and creates counter doc."""
doc_snapshot = _make_doc_snapshot(False)
mock_doc_ref, mock_transaction = _setup_service_and_mocks(mock_db, doc_snapshot)
with patch('backend.services.brand_code_service.firestore') as mock_fs, \
patch('backend.services.brand_code_service.settings') as mock_settings:
mock_settings.google_cloud_project = 'test-project'
def fake_transactional(func):
def wrapper(transaction, *args, **kwargs):
return func(transaction, *args, **kwargs)
return wrapper
mock_fs.transactional = fake_transactional
from backend.services.brand_code_service import BrandCodeService
svc = BrandCodeService(db=mock_db)
with patch.object(svc, '_get_initial_next_number', return_value=1264):
result = svc.allocate_brand_code("NOMAD", "/Karaoke/Tracks-Organized")
assert result == "NOMAD-1264"
# Verify counter doc was created via transaction.set
mock_transaction.set.assert_called_once()
set_args = mock_transaction.set.call_args[0]
assert set_args[0] is mock_doc_ref
assert set_args[1]["prefix"] == "NOMAD"
assert set_args[1]["next_number"] == 1265
assert set_args[1]["recycled"] == []
def test_allocate_nomadnp_prefix(self, mock_db):
"""Test NOMADNP prefix works independently."""
doc_snapshot = _make_doc_snapshot(True, {
"prefix": "NOMADNP",
"next_number": 13,
"recycled": [],
})
_setup_service_and_mocks(mock_db, doc_snapshot)
with patch('backend.services.brand_code_service.firestore') as mock_fs, \
patch('backend.services.brand_code_service.settings') as mock_settings:
mock_settings.google_cloud_project = 'test-project'
def fake_transactional(func):
def wrapper(transaction, *args, **kwargs):
return func(transaction, *args, **kwargs)
return wrapper
mock_fs.transactional = fake_transactional
from backend.services.brand_code_service import BrandCodeService
svc = BrandCodeService(db=mock_db)
result = svc.allocate_brand_code("NOMADNP", "/Karaoke/NP")
assert result == "NOMADNP-0013"
mock_db.collection.assert_called_with("brand_code_counters")
mock_db.collection.return_value.document.assert_called_with("NOMADNP")
def test_allocate_formats_with_leading_zeros(self, mock_db):
"""Test brand codes are zero-padded to 4 digits."""
doc_snapshot = _make_doc_snapshot(True, {
"prefix": "NOMADNP",
"next_number": 5,
"recycled": [],
})
_setup_service_and_mocks(mock_db, doc_snapshot)
with patch('backend.services.brand_code_service.firestore') as mock_fs, \
patch('backend.services.brand_code_service.settings') as mock_settings:
mock_settings.google_cloud_project = 'test-project'
def fake_transactional(func):
def wrapper(transaction, *args, **kwargs):
return func(transaction, *args, **kwargs)
return wrapper
mock_fs.transactional = fake_transactional
from backend.services.brand_code_service import BrandCodeService
svc = BrandCodeService(db=mock_db)
result = svc.allocate_brand_code("NOMADNP", "/path")
assert result == "NOMADNP-0005"
class TestBrandCodeServiceRecycle:
"""Test recycle_brand_code method."""
@pytest.fixture
def mock_db(self):
return MagicMock()
def test_recycle_adds_number_to_pool(self, mock_db):
"""Test recycling adds number to the recycled list."""
doc_snapshot = _make_doc_snapshot(True, {
"prefix": "NOMAD",
"next_number": 1264,
"recycled": [1250],
})
mock_doc_ref, mock_transaction = _setup_service_and_mocks(mock_db, doc_snapshot)
with patch('backend.services.brand_code_service.firestore') as mock_fs, \
patch('backend.services.brand_code_service.settings') as mock_settings:
mock_settings.google_cloud_project = 'test-project'
def fake_transactional(func):
def wrapper(transaction, *args, **kwargs):
return func(transaction, *args, **kwargs)
return wrapper
mock_fs.transactional = fake_transactional
from backend.services.brand_code_service import BrandCodeService
svc = BrandCodeService(db=mock_db)
svc.recycle_brand_code("NOMAD", 1230)
update_args = mock_transaction.update.call_args[0][1]
assert 1230 in update_args["recycled"]
assert 1250 in update_args["recycled"]
def test_recycle_rejects_number_at_or_above_next(self, mock_db):
"""Test recycling a number >= next_number is rejected."""
doc_snapshot = _make_doc_snapshot(True, {
"prefix": "NOMAD",
"next_number": 1264,
"recycled": [],
})
mock_doc_ref, mock_transaction = _setup_service_and_mocks(mock_db, doc_snapshot)
with patch('backend.services.brand_code_service.firestore') as mock_fs, \
patch('backend.services.brand_code_service.settings') as mock_settings:
mock_settings.google_cloud_project = 'test-project'
def fake_transactional(func):
def wrapper(transaction, *args, **kwargs):
return func(transaction, *args, **kwargs)
return wrapper
mock_fs.transactional = fake_transactional
from backend.services.brand_code_service import BrandCodeService
svc = BrandCodeService(db=mock_db)
# Number equal to next_number — hasn't been allocated yet
svc.recycle_brand_code("NOMAD", 1264)
mock_transaction.update.assert_not_called()
def test_recycle_rejects_zero_or_negative(self, mock_db):
"""Test recycling zero or negative numbers is rejected."""
doc_snapshot = _make_doc_snapshot(True, {
"prefix": "NOMAD",
"next_number": 1264,
"recycled": [],
})
mock_doc_ref, mock_transaction = _setup_service_and_mocks(mock_db, doc_snapshot)
with patch('backend.services.brand_code_service.firestore') as mock_fs, \
patch('backend.services.brand_code_service.settings') as mock_settings:
mock_settings.google_cloud_project = 'test-project'
def fake_transactional(func):
def wrapper(transaction, *args, **kwargs):
return func(transaction, *args, **kwargs)
return wrapper
mock_fs.transactional = fake_transactional
from backend.services.brand_code_service import BrandCodeService
svc = BrandCodeService(db=mock_db)
svc.recycle_brand_code("NOMAD", 0)
mock_transaction.update.assert_not_called()
def test_recycle_skips_duplicate(self, mock_db):
"""Test recycling a number already in the pool doesn't duplicate it."""
doc_snapshot = _make_doc_snapshot(True, {
"prefix": "NOMAD",
"next_number": 1264,
"recycled": [1250],
})
mock_doc_ref, mock_transaction = _setup_service_and_mocks(mock_db, doc_snapshot)
with patch('backend.services.brand_code_service.firestore') as mock_fs, \
patch('backend.services.brand_code_service.settings') as mock_settings:
mock_settings.google_cloud_project = 'test-project'
def fake_transactional(func):
def wrapper(transaction, *args, **kwargs):
return func(transaction, *args, **kwargs)
return wrapper
mock_fs.transactional = fake_transactional
from backend.services.brand_code_service import BrandCodeService
svc = BrandCodeService(db=mock_db)
svc.recycle_brand_code("NOMAD", 1250)
mock_transaction.update.assert_not_called()
def test_recycle_no_counter_doc_logs_warning(self, mock_db):
"""Test recycling when counter doc doesn't exist logs warning and returns."""
doc_snapshot = _make_doc_snapshot(False)
mock_doc_ref, mock_transaction = _setup_service_and_mocks(mock_db, doc_snapshot)
with patch('backend.services.brand_code_service.firestore') as mock_fs, \
patch('backend.services.brand_code_service.settings') as mock_settings:
mock_settings.google_cloud_project = 'test-project'
def fake_transactional(func):
def wrapper(transaction, *args, **kwargs):
return func(transaction, *args, **kwargs)
return wrapper
mock_fs.transactional = fake_transactional
from backend.services.brand_code_service import BrandCodeService
svc = BrandCodeService(db=mock_db)
svc.recycle_brand_code("NOMAD", 1230)
mock_transaction.update.assert_not_called()
mock_transaction.set.assert_not_called()
class TestBrandCodeServiceRecycleRoundTrip:
"""Test recycle-then-allocate round trip."""
@pytest.fixture
def mock_db(self):
return MagicMock()
def test_recycle_then_allocate_reuses_number(self, mock_db):
"""Test that a recycled number is returned on next allocation."""
mock_doc_ref = Mock()
mock_db.collection.return_value.document.return_value = mock_doc_ref
mock_transaction = Mock()
mock_db.transaction.return_value = mock_transaction
with patch('backend.services.brand_code_service.firestore') as mock_fs, \
patch('backend.services.brand_code_service.settings') as mock_settings:
mock_settings.google_cloud_project = 'test-project'
def fake_transactional(func):
def wrapper(transaction, *args, **kwargs):
return func(transaction, *args, **kwargs)
return wrapper
mock_fs.transactional = fake_transactional
from backend.services.brand_code_service import BrandCodeService
svc = BrandCodeService(db=mock_db)
# Step 1: Recycle number 1230
mock_doc_ref.get.return_value = _make_doc_snapshot(True, {
"prefix": "NOMAD",
"next_number": 1264,
"recycled": [],
})
svc.recycle_brand_code("NOMAD", 1230)
# Step 2: Allocate — should get recycled 1230
mock_doc_ref.get.return_value = _make_doc_snapshot(True, {
"prefix": "NOMAD",
"next_number": 1264,
"recycled": [1230],
})
result = svc.allocate_brand_code("NOMAD", "/path")
assert result == "NOMAD-1230"
class TestInitializeFromDropbox:
"""Test _get_initial_next_number."""
@pytest.fixture
def mock_db(self):
return MagicMock()
def test_init_from_dropbox_finds_max(self, mock_db):
"""Test initialization finds the max existing number and adds 1."""
mock_dropbox = Mock()
mock_dropbox.is_configured = True
mock_dropbox.list_folders.return_value = [
"NOMAD-1260 - Artist A - Song A",
"NOMAD-1261 - Artist B - Song B",
"NOMAD-1263 - Artist C - Song C",
"Some Other Folder",
]
with patch('backend.services.brand_code_service.settings') as mock_settings, \
patch('backend.services.dropbox_service.get_dropbox_service', return_value=mock_dropbox):
mock_settings.google_cloud_project = 'test-project'
from backend.services.brand_code_service import BrandCodeService
svc = BrandCodeService(db=mock_db)
result = svc._get_initial_next_number("NOMAD", "/Karaoke/Tracks-Organized")
assert result == 1264 # max(1260, 1261, 1263) + 1
def test_init_from_dropbox_no_existing(self, mock_db):
"""Test initialization returns 1 when no existing codes found."""
mock_dropbox = Mock()
mock_dropbox.is_configured = True
mock_dropbox.list_folders.return_value = ["Some Random Folder"]
with patch('backend.services.brand_code_service.settings') as mock_settings, \
patch('backend.services.dropbox_service.get_dropbox_service', return_value=mock_dropbox):
mock_settings.google_cloud_project = 'test-project'
from backend.services.brand_code_service import BrandCodeService
svc = BrandCodeService(db=mock_db)
result = svc._get_initial_next_number("NOMAD", "/path")
assert result == 1
def test_init_from_dropbox_not_configured(self, mock_db):
"""Test initialization returns 1 when Dropbox not configured."""
mock_dropbox = Mock()
mock_dropbox.is_configured = False
with patch('backend.services.brand_code_service.settings') as mock_settings, \
patch('backend.services.dropbox_service.get_dropbox_service', return_value=mock_dropbox):
mock_settings.google_cloud_project = 'test-project'
from backend.services.brand_code_service import BrandCodeService
svc = BrandCodeService(db=mock_db)
result = svc._get_initial_next_number("NOMAD", "/path")
assert result == 1
def test_init_nomadnp_prefix_independent(self, mock_db):
"""Test NOMADNP initialization only finds NOMADNP codes, not NOMAD."""
mock_dropbox = Mock()
mock_dropbox.is_configured = True
mock_dropbox.list_folders.return_value = [
"NOMADNP-0010 - Artist A",
"NOMADNP-0012 - Artist B",
"NOMAD-1263 - Artist C", # Should NOT match NOMADNP prefix
]
with patch('backend.services.brand_code_service.settings') as mock_settings, \
patch('backend.services.dropbox_service.get_dropbox_service', return_value=mock_dropbox):
mock_settings.google_cloud_project = 'test-project'
from backend.services.brand_code_service import BrandCodeService
svc = BrandCodeService(db=mock_db)
result = svc._get_initial_next_number("NOMADNP", "/Karaoke/NP")
assert result == 13 # max(10, 12) + 1
class TestParseBrandCode:
"""Test parse_brand_code static method."""
def test_parse_nomad_code(self):
from backend.services.brand_code_service import BrandCodeService
prefix, number = BrandCodeService.parse_brand_code("NOMAD-1234")
assert prefix == "NOMAD"
assert number == 1234
def test_parse_nomadnp_code(self):
from backend.services.brand_code_service import BrandCodeService
prefix, number = BrandCodeService.parse_brand_code("NOMADNP-0012")
assert prefix == "NOMADNP"
assert number == 12
def test_parse_leading_zeros(self):
from backend.services.brand_code_service import BrandCodeService
prefix, number = BrandCodeService.parse_brand_code("NOMAD-0001")
assert prefix == "NOMAD"
assert number == 1
def test_parse_invalid_format_raises(self):
from backend.services.brand_code_service import BrandCodeService
with pytest.raises(ValueError, match="Invalid brand code format"):
BrandCodeService.parse_brand_code("invalid")
def test_parse_no_dash_raises(self):
from backend.services.brand_code_service import BrandCodeService
with pytest.raises(ValueError, match="Invalid brand code format"):
BrandCodeService.parse_brand_code("NOMAD1234")
def test_parse_lowercase_raises(self):
from backend.services.brand_code_service import BrandCodeService
with pytest.raises(ValueError, match="Invalid brand code format"):
BrandCodeService.parse_brand_code("nomad-1234")
class TestCleanupDistributionRecycling:
"""Test that cleanup_distribution endpoint recycles brand codes correctly."""
def test_parse_and_recycle_nomad_brand_code(self):
"""Test that a NOMAD brand code is correctly parsed and recycled."""
from backend.services.brand_code_service import BrandCodeService
prefix, number = BrandCodeService.parse_brand_code("NOMAD-1234")
assert prefix == "NOMAD"
assert number == 1234
def test_parse_and_recycle_nomadnp_brand_code(self):
"""Test that a NOMADNP brand code is correctly parsed and recycled."""
from backend.services.brand_code_service import BrandCodeService
prefix, number = BrandCodeService.parse_brand_code("NOMADNP-0012")
assert prefix == "NOMADNP"
assert number == 12
def test_recycle_called_after_successful_dropbox_delete(self):
"""Test the integration pattern: parse brand code, then recycle the number."""
mock_db = MagicMock()
mock_doc_ref = Mock()
mock_db.collection.return_value.document.return_value = mock_doc_ref
mock_transaction = Mock()
mock_db.transaction.return_value = mock_transaction
mock_doc_ref.get.return_value = _make_doc_snapshot(True, {
"prefix": "NOMAD",
"next_number": 1264,
"recycled": [],
})
with patch('backend.services.brand_code_service.firestore') as mock_fs, \
patch('backend.services.brand_code_service.settings') as mock_settings:
mock_settings.google_cloud_project = 'test-project'
def fake_transactional(func):
def wrapper(transaction, *args, **kwargs):
return func(transaction, *args, **kwargs)
return wrapper
mock_fs.transactional = fake_transactional
from backend.services.brand_code_service import BrandCodeService
svc = BrandCodeService(db=mock_db)
# Simulate what cleanup_distribution does:
# 1. Parse the brand code
brand_code = "NOMAD-1234"
prefix, number = BrandCodeService.parse_brand_code(brand_code)
# 2. Recycle it
svc.recycle_brand_code(prefix, number)
# Verify transaction.update was called to add 1234 to recycled pool
mock_transaction.update.assert_called_once()
update_args = mock_transaction.update.call_args[0][1]
assert 1234 in update_args["recycled"]
def test_recycle_failure_does_not_raise(self):
"""Test that recycling a brand code with no counter doc doesn't raise."""
mock_db = MagicMock()
mock_doc_ref = Mock()
mock_db.collection.return_value.document.return_value = mock_doc_ref
mock_transaction = Mock()
mock_db.transaction.return_value = mock_transaction
mock_doc_ref.get.return_value = _make_doc_snapshot(False)
with patch('backend.services.brand_code_service.firestore') as mock_fs, \
patch('backend.services.brand_code_service.settings') as mock_settings:
mock_settings.google_cloud_project = 'test-project'
def fake_transactional(func):
def wrapper(transaction, *args, **kwargs):
return func(transaction, *args, **kwargs)
return wrapper
mock_fs.transactional = fake_transactional
from backend.services.brand_code_service import BrandCodeService
svc = BrandCodeService(db=mock_db)
# Should not raise — cleanup should be resilient
svc.recycle_brand_code("NOMAD", 1234)
mock_transaction.update.assert_not_called()
class TestGetBrandCodeService:
"""Test singleton getter."""
def test_returns_same_instance(self):
"""Test get_brand_code_service returns singleton."""
with patch('backend.services.brand_code_service.settings') as mock_settings:
mock_settings.google_cloud_project = 'test-project'
import backend.services.brand_code_service as module
# Reset singleton
module._brand_code_service = None
svc1 = module.get_brand_code_service()
svc2 = module.get_brand_code_service()
assert svc1 is svc2
# Clean up
module._brand_code_service = None
@@ -611,7 +611,7 @@ class TestVideoWorkerOrchestratorOrganization:
@pytest.mark.asyncio
async def test_run_organization_generate_brand_code(self):
"""Test brand code generation from Dropbox."""
"""Test brand code generation via atomic BrandCodeService."""
config = OrchestratorConfig(
job_id="test-job",
artist="Test Artist",
@@ -624,15 +624,15 @@ class TestVideoWorkerOrchestratorOrganization:
)
orchestrator = VideoWorkerOrchestrator(config)
with patch("backend.services.dropbox_service.get_dropbox_service") as mock_get:
mock_dropbox = MagicMock()
mock_dropbox.is_configured = True
mock_dropbox.get_next_brand_code.return_value = "TEST-0001"
mock_get.return_value = mock_dropbox
with patch("backend.services.brand_code_service.get_brand_code_service") as mock_get:
mock_service = MagicMock()
mock_service.allocate_brand_code.return_value = "TEST-0001"
mock_get.return_value = mock_service
await orchestrator._run_organization()
assert orchestrator.result.brand_code == "TEST-0001"
mock_service.allocate_brand_code.assert_called_once_with("TEST", "/Karaoke/Tracks")
class TestVideoWorkerOrchestratorDistribution:
+4 -2
View File
@@ -800,9 +800,11 @@ async def _handle_native_distribution(
else:
job_log.info(f"Starting native Dropbox upload to {dropbox_path}")
# Calculate brand code from existing folders (if not already generated)
# Calculate brand code atomically (if not already generated)
if not brand_code:
brand_code = dropbox.get_next_brand_code(dropbox_path, brand_prefix)
from backend.services.brand_code_service import get_brand_code_service
brand_code_service = get_brand_code_service()
brand_code = brand_code_service.allocate_brand_code(brand_prefix, dropbox_path)
result['brand_code'] = brand_code
job_log.info(f"Generated brand code: {brand_code}")
+8 -11
View File
@@ -468,18 +468,15 @@ class VideoWorkerOrchestrator:
# Generate brand code from Dropbox if configured
if self.config.dropbox_path and self.config.brand_prefix:
try:
from backend.services.dropbox_service import get_dropbox_service
from backend.services.brand_code_service import get_brand_code_service
dropbox = get_dropbox_service()
if dropbox.is_configured:
brand_code = dropbox.get_next_brand_code(
self.config.dropbox_path,
self.config.brand_prefix
)
self.result.brand_code = brand_code
self.job_log.info(f"Generated brand code: {brand_code}")
else:
self.job_log.warning("Dropbox not configured, skipping brand code generation")
brand_code_service = get_brand_code_service()
brand_code = brand_code_service.allocate_brand_code(
self.config.brand_prefix,
self.config.dropbox_path
)
self.result.brand_code = brand_code
self.job_log.info(f"Generated brand code: {brand_code}")
except Exception as e:
self.job_log.error(f"Brand code generation failed: {e}")
+3
View File
@@ -675,6 +675,9 @@ When adding alternative implementations (GCE vs local encoding), audit ALL side
### External Response Validation
Add defensive type checking for all external service responses. Lists vs dicts, missing fields cause cryptic failures.
### Brand Code Allocation Must Be Atomic (Feb 2026)
Two concurrent jobs both got brand code `NOMADNP-0012` because `get_next_brand_code()` scanned Dropbox folders to find the next number — a classic TOCTOU race condition. Jobs processed 0.86s apart both saw the same state. **Fix**: `brand_code_service.py` uses Firestore transactions to atomically allocate codes. Counter doc per prefix (`NOMAD`, `NOMADNP`) with `next_number` and `recycled` pool. E2E cleanup recycles numbers via `recycle_brand_code()`.
---
## Frontend Patterns
+1 -1
View File
@@ -1,6 +1,6 @@
[tool.poetry]
name = "karaoke-gen"
version = "0.119.4"
version = "0.119.5"
description = "Generate karaoke videos with synchronized lyrics. Handles the entire process from downloading audio and lyrics to creating the final video with title screens."
authors = ["Andrew Beveridge <andrew@beveridge.uk>"]
license = "MIT"