Skip to content
Merged
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
9 changes: 9 additions & 0 deletions docs/02_concepts/11_pay_per_event.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ import ConditionalActorChargeSource from '!!raw-loader!roa-loader!./code/11_cond
import ChargeLimitCheckSource from '!!raw-loader!roa-loader!./code/11_charge_limit_check.py';
import AdvancedChargingExample from '!!raw-loader!roa-loader!./code/11_advanced_charging.py';
import ChargePerUnitSource from '!!raw-loader!roa-loader!./code/11_charge_per_unit.py';
import MultiTenantChargeSource from '!!raw-loader!roa-loader!./code/11_multi_tenant_charge.py';
import ApiLink from '@theme/ApiLink';
import RunnableCodeBlock from '@site/src/components/RunnableCodeBlock';

Expand Down Expand Up @@ -38,6 +39,14 @@ If you can split your work into individual units, for example scraping one page

If you use the `count` parameter, always check the returned `charged_count`. It tells you how many events were charged, which may be less than what you requested.

### Charge in multi-tenant Server Actors

A multi-tenant [Server Actor](https://docs.apify.com/platform/actors/development/programming-interface/standby) (formerly Actor Standby) run serves requests from many users. To charge the user who made a request rather than the account that started the run, pass the request's `X-Actor-Request-ID` header value as `request_id`. Multi-tenant runs reject charges without it.

<RunnableCodeBlock className="language-python" language="python">
{MultiTenantChargeSource}
</RunnableCodeBlock>

### Retry charges safely

When an operation may be retried, for example after a network error, pass an `idempotency_key` to `Actor.charge()`. A repeated call under the same key isn't charged again. It reports the `charged_count` of the original call:
Expand Down
42 changes: 42 additions & 0 deletions docs/02_concepts/code/11_multi_tenant_charge.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
import asyncio
from typing import Annotated

import uvicorn
from fastapi import FastAPI, Header

from apify import Actor

app = FastAPI()


@app.get('/')
async def index(
x_actor_request_id: Annotated[str | None, Header()] = None,
x_apify_container_server_readiness_probe: Annotated[str | None, Header()] = None,
) -> str:
# The platform checks that the server is ready before it sends any requests.
if x_apify_container_server_readiness_probe is not None:
return 'ready'

# The platform identifies the caller of each request with this header.
# Pass it along so the charge lands on the caller's account, not yours.
# Locally, the header is missing and the charge goes to the local log.
if x_actor_request_id is None:
await Actor.charge(event_name='api-call')
else:
await Actor.charge(event_name='api-call', request_id=x_actor_request_id)
return 'done'


async def main() -> None:
async with Actor:
config = uvicorn.Config(
app,
host='0.0.0.0', # noqa: S104
port=Actor.configuration.web_server_port,
)
await uvicorn.Server(config).serve()


if __name__ == '__main__':
asyncio.run(main())
2 changes: 1 addition & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ keywords = [
"scraping",
]
dependencies = [
"apify-client[brotli]>=3.3.0,<4.0.0",
"apify-client[brotli]>=3.5.0,<4.0.0",
"crawlee>=1.9.1,<2.0.0,!=1.10.1",
"cachetools>=5.5.0",
"cryptography>=42.0.0",
Expand Down
40 changes: 34 additions & 6 deletions src/apify/_actor.py
Original file line number Diff line number Diff line change
Expand Up @@ -774,11 +774,18 @@ async def push_data(self, data: dict | list[dict], *, charged_event_name: str |
Args:
data: The data to push to the default dataset.
charged_event_name: If provided and if the Actor uses the pay-per-event pricing model,
the method will attempt to charge for the event for each pushed item.
the method will attempt to charge for the event for each pushed item. Not supported in multi-tenant
Server Actor runs, which charge per request with `Actor.charge()`.
"""
if charged_event_name and charged_event_name.startswith('apify-'):
raise ValueError(f'Cannot charge for synthetic event "{charged_event_name}" manually')

if charged_event_name and self._charging_manager_implementation.is_multi_tenant:
raise ValueError(
'Charging for pushed items is not supported in a multi-tenant Server Actor run - use '
'Actor.charge() with the `request_id` of the incoming request instead.'
)

charging_manager = self.get_charging_manager()

if not data:
Expand Down Expand Up @@ -926,8 +933,22 @@ def get_charging_manager(self) -> ChargingManager:
"""Retrieve the charging manager to access granular pricing information."""
return self._charging_manager_implementation

@overload
async def charge(self, event_name: str, *, count: int = 1, idempotency_key: str | None = None) -> ChargeResult: ...
@overload
async def charge(
self, event_name: str, *, count: int = 1, idempotency_key: str | None = None, request_id: str
) -> ChargeResult: ...

@_ensure_context
async def charge(self, event_name: str, *, count: int = 1, idempotency_key: str | None = None) -> ChargeResult:
async def charge(
self,
event_name: str,
*,
count: int = 1,
idempotency_key: str | None = None,
request_id: str | None = None,
) -> ChargeResult:
"""Charge for a specified number of events - sub-operations of the Actor.

This is relevant only for the pay-per-event pricing model.
Expand All @@ -941,11 +962,18 @@ async def charge(self, event_name: str, *, count: int = 1, idempotency_key: str
idempotency_key: A unique key preventing a retried operation from being charged for twice. A repeat
under the same key within three minutes is not sent to the API and reports the `charged_count` of
the original call, or zero if it names a different event. Like the platform, the key is forgotten
afterwards.
afterwards. In a multi-tenant Server Actor run, every call is sent and the platform deduplicates it.
The key is scoped to the whole run there, so a key reused by another caller charges only the first
one - derive it from `request_id`.
request_id: ID of the Server Actor request being charged, taken from the `X-Actor-Request-ID` header of
the incoming request. Required in multi-tenant Server Actor runs, where it maps the charge to the
caller's account instead of the account that started the run. Ignored elsewhere.
"""
# charging_manager.charge() acquires charge_lock internally.
charging_manager = self.get_charging_manager()
return await charging_manager.charge(event_name, count=count, idempotency_key=idempotency_key)
# The implementation's `charge()` acquires charge_lock internally and, unlike the public overloads, takes the
# `None` default of `request_id`.
return await self._charging_manager_implementation.charge(
event_name, count=count, idempotency_key=idempotency_key, request_id=request_id
)

@overload
def on(
Expand Down
123 changes: 116 additions & 7 deletions src/apify/_charging.py
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
from datetime import UTC, datetime
from decimal import Decimal
from logging import getLogger
from typing import TYPE_CHECKING, Literal, Protocol, TypedDict
from typing import TYPE_CHECKING, Literal, Protocol, TypedDict, overload

from cachetools import TTLCache
from pydantic import BaseModel, ConfigDict, Field, ValidationError
Expand Down Expand Up @@ -94,7 +94,21 @@ class ChargingManager(Protocol):
charge_lock: ReentrantLock
"""Lock to synchronize charge operations. Prevents race conditions between `charge` and `push_data` calls."""

async def charge(self, event_name: str, *, count: int = 1, idempotency_key: str | None = None) -> ChargeResult:
@overload
async def charge(self, event_name: str, *, count: int = 1, idempotency_key: str | None = None) -> ChargeResult: ...
@overload
async def charge(
self, event_name: str, *, count: int = 1, idempotency_key: str | None = None, request_id: str
) -> ChargeResult: ...

async def charge(
self,
event_name: str,
*,
count: int = 1,
idempotency_key: str | None = None,
request_id: str | None = None,
) -> ChargeResult:
"""Charge for a specified number of events - sub-operations of the Actor.

This is relevant only for the pay-per-event pricing model.
Expand All @@ -108,7 +122,12 @@ async def charge(self, event_name: str, *, count: int = 1, idempotency_key: str
idempotency_key: A unique key preventing a retried operation from being charged for twice. A repeat
under the same key within three minutes is not sent to the API and reports the `charged_count` of
the original call, or zero if it names a different event. Like the platform, the key is forgotten
afterwards.
afterwards. In a multi-tenant Server Actor run, every call is sent and the platform deduplicates it.
The key is scoped to the whole run there, so a key reused by another caller charges only the first
one - derive it from `request_id`.
request_id: ID of the Server Actor request being charged, taken from the `X-Actor-Request-ID` header of
the incoming request. Required in multi-tenant Server Actor runs, where it maps the charge to the
caller's account instead of the account that started the run. Ignored elsewhere.
"""

def calculate_total_charged_amount(self) -> Decimal:
Expand Down Expand Up @@ -216,6 +235,9 @@ def __init__(self, configuration: Configuration, client: ApifyClientAsync) -> No
self._actor_run_id = configuration.actor_run_id
self._purge_charging_log_dataset = configuration.purge_on_start
self._pricing_model: PricingModel | None = None
self.is_multi_tenant = False
"""Multi-tenant Server Actor runs carry no pricing snapshot; pricing comes from the Actor and the platform
prices and limits each caller separately."""

self._client = client
self._charging_log_dataset: Dataset | None = None
Expand Down Expand Up @@ -278,7 +300,9 @@ async def __aenter__(self) -> None:
self._charging_state = RecoverableState(
default_state=ChargingState(),
persist_state_key=CHARGING_STATE_KEY,
persistence_enabled=self._is_at_home and self._pricing_model == 'PAY_PER_EVENT',
persistence_enabled=(
self._is_at_home and self._pricing_model == 'PAY_PER_EVENT' and not self.is_multi_tenant
),
persist_state_kvs_factory=KeyValueStore.open,
logger=logger,
)
Expand All @@ -303,8 +327,9 @@ async def __aenter__(self) -> None:
self._charging_log_dataset = await Dataset.open(name=self.LOCAL_CHARGING_LOG_DATASET_NAME)

# if the Actor runs with the pay-per-event pricing model, set the context variable so that PPE-aware dataset
# clients can access the charging manager and charge for synthetic events.
if self._pricing_model == 'PAY_PER_EVENT':
# clients can access the charging manager and charge for synthetic events. Multi-tenant runs charge per request
# only, so dataset writes charge nothing there.
if self._pricing_model == 'PAY_PER_EVENT' and not self.is_multi_tenant:
charging_manager_ctx.set(self)

async def __aexit__(
Expand All @@ -324,7 +349,14 @@ async def __aexit__(
self.active = False

@_ensure_context
async def charge(self, event_name: str, *, count: int = 1, idempotency_key: str | None = None) -> ChargeResult:
async def charge(
self,
event_name: str,
*,
count: int = 1,
idempotency_key: str | None = None,
request_id: str | None = None,
) -> ChargeResult:
if idempotency_key is not None and not idempotency_key.strip():
raise ValueError('idempotency_key must not be blank')

Expand All @@ -342,6 +374,11 @@ async def charge(self, event_name: str, *, count: int = 1, idempotency_key: str
chargeable_within_limit=self.compute_chargeable(),
)

if self.is_multi_tenant:
return await self._charge_server_request(
event_name, count=count, idempotency_key=idempotency_key, request_id=request_id
)

if count <= 0:
return ChargeResult(
event_charge_limit_reached=self.is_event_charge_limit_reached(event_name),
Expand Down Expand Up @@ -404,6 +441,7 @@ async def charge(self, event_name: str, *, count: int = 1, idempotency_key: str
event_name,
count=charged_count,
idempotency_key=idempotency_key,
request_id=request_id,
)
logger.debug("Charged %d occurrence(s) of event '%s'.", charged_count, event_name)
elif event_name in self._tier_priced_events:
Expand Down Expand Up @@ -434,6 +472,7 @@ async def charge(self, event_name: str, *, count: int = 1, idempotency_key: str
'event_price_usd': float(round(pricing_info.price, 3)),
'charged_count': charged_count,
'idempotency_key': idempotency_key,
'request_id': request_id,
'timestamp': datetime.now(UTC).isoformat(),
}
)
Expand Down Expand Up @@ -558,6 +597,10 @@ async def _fetch_pricing_info(self) -> _FetchedPricingInfoDict:
if run is None:
raise RuntimeError('Actor run not found')

if run.standby is not None and run.standby.deployment.startswith('MULTI_TENANT'):
self.is_multi_tenant = True
return await self._fetch_multi_tenant_pricing_info()

max_charge = run.options.max_total_charge_usd
return _FetchedPricingInfoDict(
pricing_info=run.pricing_info,
Expand All @@ -576,6 +619,72 @@ async def _fetch_pricing_info(self) -> _FetchedPricingInfoDict:
),
)

async def _fetch_multi_tenant_pricing_info(self) -> _FetchedPricingInfoDict:
actor_id = self._configuration.actor_id
if actor_id is None:
raise RuntimeError('Actor ID not found even though the Actor is running on Apify')

actor = await self._client.actor(actor_id).get()
if actor is None:
raise RuntimeError('Actor not found')

# The history includes scheduled future changes, so the effective entry is the latest one that has started.
# Resolved once on purpose - the platform prices each charge from its own current pricing anyway.
Comment thread
vdusek marked this conversation as resolved.
Resolved
now = datetime.now(UTC)
started = [info for info in actor.pricing_infos or [] if info.started_at <= now]
pricing_info = max(started, key=lambda info: info.started_at, default=None)

# The run's `charged_event_counts` mix all callers, so they are not loaded.
return _FetchedPricingInfoDict(
pricing_info=pricing_info,
charged_event_counts={},
max_total_charge_usd=Decimal('inf'),
)

async def _charge_server_request(
self,
event_name: str,
*,
count: int,
idempotency_key: str | None,
request_id: str | None,
) -> ChargeResult:
"""Charge the caller of a multi-tenant Server Actor request.

The platform prices, limits and deduplicates each caller's charges itself, so nothing is counted or enforced
locally, and every call is sent - the platform discards a repeat under an idempotency key used earlier in the
run, even by another caller.
"""
if event_name.startswith('apify-'):
raise ValueError(f"Cannot charge for synthetic event '{event_name}' in a multi-tenant Server Actor run")

if not request_id:
raise ValueError(
f"Charging for '{event_name}' in a multi-tenant Server Actor run requires `request_id` - pass the "
"value of the incoming request's X-Actor-Request-ID header to Actor.charge()."
)

# Tier-priced events are sent too - the platform prices each charge by the caller's tier.
charged_count = 0
if count <= 0:
pass
elif event_name not in self._pricing_info and event_name not in self._tier_priced_events:
logger.warning("Attempting to charge for an unknown event '%s'", event_name)
else:
if self._actor_run_id is None:
raise RuntimeError('Actor run ID not configured')
await self._client.run(self._actor_run_id).charge(
event_name, count=count, idempotency_key=idempotency_key, request_id=request_id
)
logger.debug("Charged %d occurrence(s) of event '%s' for request '%s'.", count, event_name, request_id)
charged_count = count

return ChargeResult(
event_charge_limit_reached=False,
charged_count=charged_count,
chargeable_within_limit=self.compute_chargeable(),
)

def _compute_charged_count(self, event_name: str, count: int) -> int:
"""Compute how many of `count` events to charge, given the remaining budget."""
max_chargeable = self.calculate_max_event_charge_count_within_limit(event_name)
Expand Down
Loading
Loading