diff --git a/src/apify/_actor.py b/src/apify/_actor.py index 8e4cb431..0ecba94e 100644 --- a/src/apify/_actor.py +++ b/src/apify/_actor.py @@ -1068,7 +1068,7 @@ async def start( force_permission_level: ActorPermissionLevel | None = None, webhooks: list[Webhook] | None = None, run_name: str | None = None, - abort_with_parent: bool = False, + abort_with_parent: bool | None = None, ) -> Run: """Run an Actor on the Apify platform. @@ -1109,17 +1109,16 @@ async def start( migration. To start a new run for an identical call, e.g. when polling, pass a `run_name` that differs between the calls. abort_with_parent: If true, the child run is gracefully aborted when this Actor run is gracefully - aborted. It requires `run_name`, and the value is recorded under it, replacing the one from an earlier - call. Once this Actor run is being gracefully aborted, a call with it raises a `RuntimeError` and - starts, resurrects or reattaches no run. A hard abort, a timeout or a crash of this Actor run leaves - the child running. + aborted. The value is recorded with the run, replacing the one from an earlier call under the same + run name or implicit key. If not set, a reused run keeps its recorded value, and a new run is not + aborted with this Actor run. Once this Actor run is being gracefully aborted, a call for a run marked + this way raises a `RuntimeError` and starts, resurrects or reattaches no run, unless the recorded run + `SUCCEEDED`. A hard abort, a timeout or a crash of this + Actor run leaves the child running. Returns: Info about the started Actor run """ - if abort_with_parent and run_name is None: - raise ValueError('`abort_with_parent` requires `run_name`, since only named child runs are tracked.') - if max_items is not None: _warn_max_items_deprecated() @@ -1270,7 +1269,7 @@ async def call( wait: timedelta | None = None, logger: logging.Logger | Literal['default'] | None = 'default', run_name: str | None = None, - abort_with_parent: bool = False, + abort_with_parent: bool | None = None, ) -> Run: """Start an Actor on the Apify Platform and wait for it to finish before returning. @@ -1314,17 +1313,16 @@ async def call( migration. To start a new run for an identical call, e.g. when polling, pass a `run_name` that differs between the calls. abort_with_parent: If true, the child run is gracefully aborted when this Actor run is gracefully - aborted. It requires `run_name`, and the value is recorded under it, replacing the one from an earlier - call. Once this Actor run is being gracefully aborted, a call with it raises a `RuntimeError` and - starts, resurrects or reattaches no run. A hard abort, a timeout or a crash of this Actor run leaves - the child running. + aborted. The value is recorded with the run, replacing the one from an earlier call under the same + run name or implicit key. If not set, a reused run keeps its recorded value, and a new run is not + aborted with this Actor run. Once this Actor run is being gracefully aborted, a call for a run marked + this way raises a `RuntimeError` and starts, resurrects or reattaches no run, unless the recorded run + `SUCCEEDED`. A hard abort, a timeout or a crash of this + Actor run leaves the child running. Returns: Info about the started Actor run. """ - if abort_with_parent and run_name is None: - raise ValueError('`abort_with_parent` requires `run_name`, since only named child runs are tracked.') - if max_items is not None: _warn_max_items_deprecated() @@ -1390,7 +1388,7 @@ async def _find_or_start_child_run( memory_mbytes: int | None, timeout: timedelta | Literal['inherit'] | None, webhooks: list[Webhook] | None, - abort_with_parent: bool, + abort_with_parent: bool | None, ) -> tuple[Run, bool]: run_options = { 'content_type': content_type, @@ -1466,7 +1464,7 @@ async def start_task( webhooks: list[Webhook] | None = None, token: str | None = None, run_name: str | None = None, - abort_with_parent: bool = False, + abort_with_parent: bool | None = None, ) -> Run: """Start an Actor task on the Apify Platform. @@ -1507,17 +1505,16 @@ async def start_task( migration. To start a new run for an identical call, e.g. when polling, pass a `run_name` that differs between the calls. abort_with_parent: If true, the child run is gracefully aborted when this Actor run is gracefully - aborted. It requires `run_name`, and the value is recorded under it, replacing the one from an earlier - call. Once this Actor run is being gracefully aborted, a call with it raises a `RuntimeError` and - starts, resurrects or reattaches no run. A hard abort, a timeout or a crash of this Actor run leaves - the child running. + aborted. The value is recorded with the run, replacing the one from an earlier call under the same + run name or implicit key. If not set, a reused run keeps its recorded value, and a new run is not + aborted with this Actor run. Once this Actor run is being gracefully aborted, a call for a run marked + this way raises a `RuntimeError` and starts, resurrects or reattaches no run, unless the recorded run + `SUCCEEDED`. A hard abort, a timeout or a crash of this + Actor run leaves the child running. Returns: Info about the started Actor run. """ - if abort_with_parent and run_name is None: - raise ValueError('`abort_with_parent` requires `run_name`, since only named child runs are tracked.') - if max_items is not None: _warn_max_items_deprecated() @@ -1568,7 +1565,7 @@ async def call_task( wait: timedelta | None = None, token: str | None = None, run_name: str | None = None, - abort_with_parent: bool = False, + abort_with_parent: bool | None = None, ) -> Run: """Start an Actor task on the Apify Platform and wait for it to finish before returning. @@ -1609,17 +1606,16 @@ async def call_task( migration. To start a new run for an identical call, e.g. when polling, pass a `run_name` that differs between the calls. abort_with_parent: If true, the child run is gracefully aborted when this Actor run is gracefully - aborted. It requires `run_name`, and the value is recorded under it, replacing the one from an earlier - call. Once this Actor run is being gracefully aborted, a call with it raises a `RuntimeError` and - starts, resurrects or reattaches no run. A hard abort, a timeout or a crash of this Actor run leaves - the child running. + aborted. The value is recorded with the run, replacing the one from an earlier call under the same + run name or implicit key. If not set, a reused run keeps its recorded value, and a new run is not + aborted with this Actor run. Once this Actor run is being gracefully aborted, a call for a run marked + this way raises a `RuntimeError` and starts, resurrects or reattaches no run, unless the recorded run + `SUCCEEDED`. A hard abort, a timeout or a crash of this + Actor run leaves the child running. Returns: Info about the started Actor run. """ - if abort_with_parent and run_name is None: - raise ValueError('`abort_with_parent` requires `run_name`, since only named child runs are tracked.') - if max_items is not None: _warn_max_items_deprecated() diff --git a/src/apify/_child_runs.py b/src/apify/_child_runs.py index 5b6209e0..fecd1119 100644 --- a/src/apify/_child_runs.py +++ b/src/apify/_child_runs.py @@ -140,7 +140,7 @@ async def find_or_start( client: ApifyClientAsync, start_run: Callable[[], Awaitable[Run]], resurrect_run: Callable[[str], Awaitable[Run]], - abort_with_parent: bool = False, + abort_with_parent: bool | None = None, ) -> tuple[Run, bool]: """Return the run recorded under `name` or the implicit key, or start one when there is none to reuse. @@ -159,8 +159,8 @@ async def find_or_start( client: Client used to look up the recorded run. start_run: Starts a new run of the Actor or task. resurrect_run: Resurrects the recorded run, given its ID. - abort_with_parent: Whether to abort the run when this Actor run is gracefully aborted. It replaces the - recorded value. + abort_with_parent: Whether to abort the run when this Actor run is gracefully aborted. `True` or `False` + replaces the recorded value. `None` keeps it, and a run with no recorded value is not aborted. Returns: The run, and whether it was newly started. @@ -168,29 +168,27 @@ async def find_or_start( Raises: ValueError: If the recorded run would be reused, but was started for a different Actor, task, input or run options. - RuntimeError: If `abort_with_parent` is set and this Actor run is being gracefully aborted. No run is - started, resurrected or reattached. + RuntimeError: If this Actor run is being gracefully aborted and the run is marked `abort_with_parent`, by + this call or, when the call does not set it, by the record. No run is started, resurrected or + reattached. A recorded run that `SUCCEEDED` is still returned. """ checksum = checksum_request(actor_id=actor_id, task_id=task_id, run_input=run_input, run_options=run_options) key = name if name is not None else checksum[:_IMPLICIT_KEY_HASH_LENGTH] + new_abort_with_parent = bool(abort_with_parent) async with self._name_locks.setdefault(key, asyncio.Lock()): - if abort_with_parent and self._parent_aborting: - raise RuntimeError( - f'Child run "{key}" with `abort_with_parent` was not started, since this Actor run is being ' - 'aborted.' - ) - records = await self._load() record = records.get(key) + marked = record is not None and record.abort_with_parent if abort_with_parent is None else abort_with_parent if record is None: + self._raise_if_parent_aborting(key, marked=marked) run = await self._start( key, run_name=name, checksum=checksum, start_run=start_run, - abort_with_parent=abort_with_parent, + abort_with_parent=new_abort_with_parent, ) self._clients[key] = client return run, True @@ -198,6 +196,10 @@ async def find_or_start( run_client = client.run(record.run_id) run = await _get_recorded_run(run_client) + # Only a run that already succeeded can be returned without leaving a marked run running. + if run is None or run.status != 'SUCCEEDED': + self._raise_if_parent_aborting(key, marked=marked) + if run is not None and run.status in _SETTLING_STATUSES: run = await run_client.wait_for_finish() @@ -207,7 +209,7 @@ async def find_or_start( run_name=name, checksum=checksum, start_run=start_run, - abort_with_parent=abort_with_parent, + abort_with_parent=record.abort_with_parent if abort_with_parent is None else abort_with_parent, ) self._clients[key] = client return run, True @@ -218,7 +220,7 @@ async def find_or_start( 'Use a unique `run_name` for each child run.' ) - if record.abort_with_parent != abort_with_parent: + if abort_with_parent is not None and record.abort_with_parent != abort_with_parent: await self._save(key, record.model_copy(update={'abort_with_parent': abort_with_parent})) if run.status in _RESURRECTABLE_STATUSES: @@ -231,6 +233,12 @@ async def find_or_start( self._clients[key] = client return run, False + def _raise_if_parent_aborting(self, key: str, *, marked: bool) -> None: + if marked and self._parent_aborting: + raise RuntimeError( + f'Child run "{key}" with `abort_with_parent` was not started, since this Actor run is being aborted.' + ) + def run_clients(self, default_client: ApifyClientAsync) -> dict[str, RunClientAsync]: """Return a client for the current run under each recorded key. diff --git a/tests/unit/actor/test_actor_child_runs.py b/tests/unit/actor/test_actor_child_runs.py index 583d4de8..dc697857 100644 --- a/tests/unit/actor/test_actor_child_runs.py +++ b/tests/unit/actor/test_actor_child_runs.py @@ -82,7 +82,12 @@ def implicit_key( def stored_unnamed_record( - run_id: str, status: str, *, actor_id: str | None = 'some-actor', task_id: str | None = None + run_id: str, + status: str, + *, + actor_id: str | None = 'some-actor', + task_id: str | None = None, + abort_with_parent: bool = False, ) -> dict[str, Any]: """Build a record of a child run started without a name, as it is stored in the default KVS.""" return { @@ -90,7 +95,7 @@ def stored_unnamed_record( 'status': status, 'runName': None, 'checksum': checksum_request(actor_id=actor_id, task_id=task_id, run_input=None), - 'abortWithParent': False, + 'abortWithParent': abort_with_parent, } @@ -1012,29 +1017,28 @@ async def test_child_runs_keeps_client_of_name_after_failed_lookup( @pytest.mark.parametrize( - 'method', + ('method', 'resource', 'ids'), [ - pytest.param('start', id='start'), - pytest.param('call', id='call'), - pytest.param('start_task', id='start task'), - pytest.param('call_task', id='call task'), + pytest.param('start', 'actor', {'actor_id': 'some-id'}, id='start'), + pytest.param('call', 'actor', {'actor_id': 'some-id'}, id='call'), + pytest.param('start_task', 'task', {'actor_id': None, 'task_id': 'some-id'}, id='start task'), + pytest.param('call_task', 'task', {'actor_id': None, 'task_id': 'some-id'}, id='call task'), ], ) -async def test_abort_with_parent_requires_run_name( - apify_client_async_patcher: ApifyClientAsyncPatcher, method: str +async def test_unnamed_start_records_abort_with_parent( + apify_client_async_patcher: ApifyClientAsyncPatcher, method: str, resource: str, ids: dict[str, Any] ) -> None: - """`abort_with_parent` without a `run_name` raises before any run is started.""" - for resource in ('actor', 'task'): - apify_client_async_patcher.patch(resource, 'start', return_value=make_run('new-run', 'READY')) - apify_client_async_patcher.patch(resource, 'call', return_value=make_run('new-run', 'SUCCEEDED')) + """A start without a name and with `abort_with_parent` records the flag with the run.""" + apify_client_async_patcher.patch(resource, 'start', return_value=make_run('new-run', 'READY')) + apify_client_async_patcher.patch('run', 'wait_for_finish', return_value=make_run('new-run', 'SUCCEEDED')) + kwargs: dict[str, Any] = {'logger': None} if method == 'call' else {} async with Actor: - with pytest.raises(ValueError, match='requires `run_name`'): - await getattr(Actor, method)('some-id', abort_with_parent=True) + await getattr(Actor, method)('some-id', abort_with_parent=True, **kwargs) + kvs = await Actor.open_key_value_store() + stored = await kvs.get_value(CHILD_RUNS_KEY) - for resource in ('actor', 'task'): - assert apify_client_async_patcher.calls[resource]['start'] == [] - assert apify_client_async_patcher.calls[resource]['call'] == [] + assert stored[implicit_key(**ids)]['abortWithParent'] is True async def test_named_start_records_abort_with_parent(apify_client_async_patcher: ApifyClientAsyncPatcher) -> None: @@ -1064,20 +1068,50 @@ async def test_named_call_task_records_abort_with_parent( assert stored['scrape-eu']['abortWithParent'] is True -async def test_reattach_replaces_recorded_abort_with_parent( - apify_client_async_patcher: ApifyClientAsyncPatcher, +@pytest.mark.parametrize( + ('recorded', 'passed', 'expected'), + [ + pytest.param(False, True, True, id='true replaces false'), + pytest.param(True, False, False, id='false replaces true'), + pytest.param(True, None, True, id='not set keeps true'), + pytest.param(False, None, False, id='not set keeps false'), + ], +) +async def test_reattach_records_abort_with_parent( + apify_client_async_patcher: ApifyClientAsyncPatcher, *, recorded: bool, passed: bool | None, expected: bool ) -> None: - """Reattaching under a name records the `abort_with_parent` value of the latest call.""" + """Reattaching replaces the recorded `abort_with_parent` with an explicit value and keeps it when none is passed.""" apify_client_async_patcher.patch('run', 'get', return_value=make_run('old-run', 'RUNNING')) + kwargs: dict[str, Any] = {} if passed is None else {'abort_with_parent': passed} async with Actor: - await record_child_run('scrape-eu', 'old-run') - await Actor.start('some-actor', run_name='scrape-eu', abort_with_parent=True) kvs = await Actor.open_key_value_store() + await kvs.set_value( + CHILD_RUNS_KEY, {'scrape-eu': stored_record('old-run', 'RUNNING', abort_with_parent=recorded)} + ) + await Actor._child_run_registry.load() + await Actor.start('some-actor', run_name='scrape-eu', **kwargs) stored = await kvs.get_value(CHILD_RUNS_KEY) assert stored['scrape-eu']['runId'] == 'old-run' - assert stored['scrape-eu']['abortWithParent'] is True + assert stored['scrape-eu']['abortWithParent'] is expected + + +async def test_replacing_a_failed_run_keeps_recorded_abort_with_parent( + apify_client_async_patcher: ApifyClientAsyncPatcher, +) -> None: + """A run that replaces a failed one keeps the recorded `abort_with_parent` when the call does not set it.""" + apify_client_async_patcher.patch('actor', 'start', return_value=make_run('new-run', 'READY')) + apify_client_async_patcher.patch('run', 'get', return_value=make_run('old-run', 'FAILED')) + + async with Actor: + kvs = await Actor.open_key_value_store() + await kvs.set_value(CHILD_RUNS_KEY, {'scrape-eu': stored_record('old-run', 'RUNNING', abort_with_parent=True)}) + await Actor._child_run_registry.load() + await Actor.start('some-actor', run_name='scrape-eu') + stored = await kvs.get_value(CHILD_RUNS_KEY) + + assert stored == {'scrape-eu': stored_record('new-run', 'READY', abort_with_parent=True)} async def test_aborting_event_aborts_marked_child_runs( @@ -1126,6 +1160,43 @@ async def abort_run(run_client: Any, *_args: Any, **_kwargs: Any) -> Run: assert 'Aborted child run "finished"' not in caplog.text +async def test_aborting_event_aborts_marked_unnamed_child_runs( + apify_client_async_patcher: ApifyClientAsyncPatcher, + caplog: pytest.LogCaptureFixture, + apify_event_manager: ApifyEventManager, +) -> None: + """On `ABORTING`, each unnamed child run marked `abort_with_parent`, even one recorded earlier, is aborted.""" + + async def abort_run(run_client: Any, *_args: Any, **_kwargs: Any) -> Run: + return make_run(run_client.resource_id, 'ABORTING') + + apify_client_async_patcher.patch('run', 'abort', replacement_method=abort_run) + caplog.set_level('INFO') + marked_key = implicit_key(actor_id='marked-actor') + + async with Actor: + kvs = await Actor.open_key_value_store() + await kvs.set_value( + CHILD_RUNS_KEY, + { + marked_key: stored_unnamed_record( + 'marked-run', 'RUNNING', actor_id='marked-actor', abort_with_parent=True + ), + implicit_key(actor_id='unmarked-actor'): stored_unnamed_record( + 'unmarked-run', 'RUNNING', actor_id='unmarked-actor' + ), + }, + ) + await Actor._child_run_registry.load() + apify_event_manager.emit(event=Event.ABORTING, event_data=EventAbortingData()) + await apify_event_manager.wait_for_all_listeners_to_complete() + + aborts = apify_client_async_patcher.calls['run']['abort'] + assert [args[0].resource_id for args, _ in aborts] == ['marked-run'] + assert aborts[0][1] == {'gracefully': True} + assert f'Aborted child run "{marked_key}" with the parent' in caplog.text + + async def test_aborting_event_skips_a_child_run_that_no_longer_exists( apify_client_async_patcher: ApifyClientAsyncPatcher, caplog: pytest.LogCaptureFixture, @@ -1266,10 +1337,47 @@ async def start_run() -> Run: client.run.return_value.abort.assert_awaited_once_with(gracefully=True) +async def test_aborting_waits_for_an_unnamed_start_in_flight() -> None: + """An unnamed `abort_with_parent` start in flight when the parent is aborted has its run aborted once recorded.""" + client = Mock() + client.run.return_value.abort = AsyncMock(return_value=make_run('new-run', 'ABORTING')) + started = asyncio.Event() + release = asyncio.Event() + + async def start_run() -> Run: + started.set() + await release.wait() + return make_run('new-run', 'READY') + + async with Actor: + registry = ChildRunRegistry(Actor.open_key_value_store) + start_task = asyncio.create_task( + registry.find_or_start( + None, + actor_id='some-actor', + run_input=None, + client=client, + start_run=start_run, + resurrect_run=AsyncMock(), + abort_with_parent=True, + ) + ) + await started.wait() + abort_task = asyncio.create_task(registry.abort_runs_with_parent(client)) + await asyncio.sleep(0) + assert not abort_task.done() + release.set() + await asyncio.gather(start_task, abort_task) + + client.run.assert_called_with('new-run') + client.run.return_value.abort.assert_awaited_once_with(gracefully=True) + + async def test_named_start_queued_behind_a_start_in_flight_raises_once_aborting() -> None: """A named start waiting on its name while the parent is aborted raises, and the run in flight is aborted.""" client = Mock() client.run.return_value.abort = AsyncMock(return_value=make_run('new-run', 'ABORTING')) + client.run.return_value.get = AsyncMock(return_value=make_run('new-run', 'ABORTING')) started = asyncio.Event() release = asyncio.Event() @@ -1334,6 +1442,47 @@ async def test_named_start_with_abort_with_parent_raises_once_aborting( assert stored is None +@pytest.mark.parametrize( + ('method', 'resource'), + [ + pytest.param('start', 'actor', id='start'), + pytest.param('call', 'actor', id='call'), + pytest.param('start_task', 'task', id='start task'), + pytest.param('call_task', 'task', id='call task'), + ], +) +async def test_unnamed_start_with_abort_with_parent_raises_once_aborting( + apify_client_async_patcher: ApifyClientAsyncPatcher, + apify_event_manager: ApifyEventManager, + method: str, + resource: str, +) -> None: + """After `ABORTING`, a new start without a name and with `abort_with_parent` raises and starts no run.""" + apify_client_async_patcher.patch(resource, 'start', return_value=make_run('new-run', 'READY')) + + async with Actor: + apify_event_manager.emit(event=Event.ABORTING, event_data=EventAbortingData()) + await apify_event_manager.wait_for_all_listeners_to_complete() + with pytest.raises(RuntimeError, match='being aborted'): + await getattr(Actor, method)('some-id', abort_with_parent=True) + + assert apify_client_async_patcher.calls[resource]['start'] == [] + + +async def test_unnamed_start_without_abort_with_parent_is_not_blocked_once_aborting( + apify_client_async_patcher: ApifyClientAsyncPatcher, apify_event_manager: ApifyEventManager +) -> None: + """After `ABORTING`, a start without a name and without `abort_with_parent` still starts a run.""" + apify_client_async_patcher.patch('actor', 'start', return_value=make_run('new-run', 'READY')) + + async with Actor: + apify_event_manager.emit(event=Event.ABORTING, event_data=EventAbortingData()) + await apify_event_manager.wait_for_all_listeners_to_complete() + run = await Actor.start('some-actor') + + assert run.id == 'new-run' + + async def test_named_call_once_aborting_does_not_resurrect_the_aborted_child( apify_client_async_patcher: ApifyClientAsyncPatcher, apify_event_manager: ApifyEventManager ) -> None: @@ -1356,6 +1505,46 @@ async def test_named_call_once_aborting_does_not_resurrect_the_aborted_child( assert apify_client_async_patcher.calls['actor']['start'] == [] +async def test_call_without_abort_with_parent_once_aborting_does_not_resurrect_a_marked_child( + apify_client_async_patcher: ApifyClientAsyncPatcher, apify_event_manager: ApifyEventManager +) -> None: + """After `ABORTING`, a call that does not set `abort_with_parent` leaves a child aborted with the parent alone.""" + apify_client_async_patcher.patch('run', 'abort', return_value=make_run('old-run', 'ABORTING')) + apify_client_async_patcher.patch('run', 'get', return_value=make_run('old-run', 'ABORTED')) + apify_client_async_patcher.patch('run', 'resurrect', return_value=make_run('old-run', 'RUNNING')) + + async with Actor: + kvs = await Actor.open_key_value_store() + await kvs.set_value(CHILD_RUNS_KEY, {'scrape-eu': stored_record('old-run', 'RUNNING', abort_with_parent=True)}) + await Actor._child_run_registry.load() + apify_event_manager.emit(event=Event.ABORTING, event_data=EventAbortingData()) + await apify_event_manager.wait_for_all_listeners_to_complete() + with pytest.raises(RuntimeError, match='being aborted'): + await Actor.call('some-actor', run_name='scrape-eu') + + assert apify_client_async_patcher.calls['run']['resurrect'] == [] + assert apify_client_async_patcher.calls['actor']['start'] == [] + + +async def test_succeeded_marked_child_is_returned_once_aborting( + apify_client_async_patcher: ApifyClientAsyncPatcher, apify_event_manager: ApifyEventManager +) -> None: + """After `ABORTING`, a call with `abort_with_parent` still gets a recorded run that already succeeded.""" + apify_client_async_patcher.patch('run', 'abort', return_value=make_run('old-run', 'SUCCEEDED')) + apify_client_async_patcher.patch('run', 'get', return_value=make_run('old-run', 'SUCCEEDED')) + + async with Actor: + kvs = await Actor.open_key_value_store() + await kvs.set_value(CHILD_RUNS_KEY, {'scrape-eu': stored_record('old-run', 'RUNNING', abort_with_parent=True)}) + await Actor._child_run_registry.load() + apify_event_manager.emit(event=Event.ABORTING, event_data=EventAbortingData()) + await apify_event_manager.wait_for_all_listeners_to_complete() + run = await Actor.call('some-actor', run_name='scrape-eu', abort_with_parent=True) + + assert run.id == 'old-run' + assert run.status == 'SUCCEEDED' + + async def test_named_start_without_abort_with_parent_is_not_blocked_once_aborting( apify_client_async_patcher: ApifyClientAsyncPatcher, apify_event_manager: ApifyEventManager ) -> None: