atlan-application-sdk-api 3.51.2__tar.gz → 3.52.0__tar.gz

{atlan_application_sdk_api-3.51.2 → atlan_application_sdk_api-3.52.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: atlan-application-sdk-api
-Version: 3.51.2
+Version: 3.52.0
 Summary: Experimental: the handler surface of the Atlan Application SDK, for the consolidated API host
 Project-URL: Homepage, https://github.com/atlanhq/application-sdk
 Project-URL: Source, https://github.com/atlanhq/application-sdk/tree/main/packages/api
@@ -160,7 +160,7 @@ an app answers identically from either one:
 | `POST /workflows/v1/metadata` | `Handler.fetch_metadata` |
 | `POST /workflows/v1/warmup` | `Handler.warmup` (optional) |
 | `GET /workflows/v1/configmap/{id}`, `/configmaps`, `/input-contract`, `GET`/`POST /workflows/v1/manifest` | The app's `generated/` folder, if the app package ships one |
-| `GET`/`POST /workflows/v1/config/{id}`, `POST /workflows/v1/file` | An S3 bucket named by `ATLAN_S3_BUCKET` (and `ATLAN_S3_REGION`); needs the `aws` extra. These routes return 503 when it isn't set |
+| `GET`/`POST /workflows/v1/config/{id}`, `POST /workflows/v1/file` | An S3 bucket named by `ATLAN_S3_BUCKET` (and `ATLAN_S3_REGION`), or on GCP by `ATLAN_GCP_BUCKET` (and `ATLAN_GCP_REGION`) through GCS's S3-compatible API with the `ATLAN_GCP_HMAC_ACCESS_KEY` / `ATLAN_GCP_HMAC_SECRET` keys; needs the `aws` extra. These routes return 503 when neither is set |
 | Your own routes | FastAPI routers returned from `Handler.routers()`, served after the SDK's |
 
 `build_asgi_app` takes a few keyword options:

{atlan_application_sdk_api-3.51.2 → atlan_application_sdk_api-3.52.0}/README.md

@@ -122,7 +122,7 @@ an app answers identically from either one:
 | `POST /workflows/v1/metadata` | `Handler.fetch_metadata` |
 | `POST /workflows/v1/warmup` | `Handler.warmup` (optional) |
 | `GET /workflows/v1/configmap/{id}`, `/configmaps`, `/input-contract`, `GET`/`POST /workflows/v1/manifest` | The app's `generated/` folder, if the app package ships one |
-| `GET`/`POST /workflows/v1/config/{id}`, `POST /workflows/v1/file` | An S3 bucket named by `ATLAN_S3_BUCKET` (and `ATLAN_S3_REGION`); needs the `aws` extra. These routes return 503 when it isn't set |
+| `GET`/`POST /workflows/v1/config/{id}`, `POST /workflows/v1/file` | An S3 bucket named by `ATLAN_S3_BUCKET` (and `ATLAN_S3_REGION`), or on GCP by `ATLAN_GCP_BUCKET` (and `ATLAN_GCP_REGION`) through GCS's S3-compatible API with the `ATLAN_GCP_HMAC_ACCESS_KEY` / `ATLAN_GCP_HMAC_SECRET` keys; needs the `aws` extra. These routes return 503 when neither is set |
 | Your own routes | FastAPI routers returned from `Handler.routers()`, served after the SDK's |
 
 `build_asgi_app` takes a few keyword options:

{atlan_application_sdk_api-3.51.2 → atlan_application_sdk_api-3.52.0}/application_sdk/_runtime/offload.py

@@ -39,7 +39,7 @@ from application_sdk._runtime.progress import (
     current_progress_tracker,
     declared_hold_active,
 )
-from application_sdk.errors import InvalidInputValueError
+from application_sdk.errors import InvalidInputValueError, ResourceExhaustedError
 
 logger = get_logger(__name__)
 
@@ -373,6 +373,314 @@ def _auto_hold(label: str, timeout: float | None) -> Iterator[None]:
         tracker.exit_hold(hold)
 
 
+# ---------------------------------------------------------------------------
+# Per-app containment of the blocking pool (FND-2973)
+# ---------------------------------------------------------------------------
+#
+# A timeout frees the *caller* of a ``run_in_thread`` call but cannot stop its
+# thread, so a driver call hung on a dead host keeps its pool slot until the
+# driver returns on its own. On the worker (one app per pod, the process-wide
+# ``_BLOCKING_EXECUTOR``) that damage stays inside the app that caused it. The
+# consolidated API host gives each app its own pool (``blocking_executor``), so
+# one app's hung calls cannot take another app's slots; within that app they
+# can still take every slot and queue the app's other calls behind them.
+#
+# Two pieces contain it:
+#
+# * **A per-app cap**, opt-in through :data:`OFFLOAD_MAX_THREADS_PER_APP_ENV`.
+#   A call that would take an app past its cap fails at once with a retryable
+#   ``ResourceExhaustedError`` instead of queueing, so a misbehaving app
+#   degrades only itself. On the host, keep the cap at or below the app's pool
+#   width (``blocking_threads``): above it, hung calls fill the pool first and
+#   the app's next calls queue behind them until the cap is reached. Unset (the
+#   default), nothing changes: calls queue
+#   exactly as before. A default cap would turn today's queueing into failures
+#   for any fan-out wider than the cap, and the pool width it would be derived
+#   from is not a reliable number — ``os.cpu_count()`` reports the node's
+#   cores, not the pod's CPU limit.
+# * **A per-app stranded count**: calls whose caller stopped waiting while the
+#   thread kept running. Exported as the ``offload.stranded_threads`` gauge,
+#   labelled by app only, and logged once per strand with the callable's name.
+#
+# A slot is held from submit until the *thread* finishes — released in the
+# executor future's done callback, never when the awaiting coroutine returns.
+# Releasing on the caller's side would let a hung thread hand back its quota
+# while it still holds its pool slot, which is the one thing the cap exists to
+# prevent. The done callback also fires for a queued call cancelled before it
+# started, so that case does not leak a slot either.
+
+#: Env var capping how many ``run_in_thread`` calls one app may have in flight
+#: (running or queued) at once. Unset or empty means no cap.
+OFFLOAD_MAX_THREADS_PER_APP_ENV = "ATLAN_OFFLOAD_MAX_THREADS_PER_APP"
+
+#: The app a ``run_in_thread`` call is charged to. Bound by the handler layer
+#: (``bind_handler_context``) for each handler invocation, and on the
+#: consolidated host for every request to an app (``handler.asgi``); otherwise
+#: the process's own ``ATLAN_APPLICATION_NAME``. On the host that fallback is
+#: the host's name, which is correct for what reaches it: startup and background
+#: work that belongs to no single app.
+_OFFLOAD_OWNER: contextvars.ContextVar[str | None] = contextvars.ContextVar(
+    "_OFFLOAD_OWNER", default=None
+)
+
+#: Read at call time, not through ``application_sdk.constants``: that module
+#: loads ``.env`` and is not part of the api distribution's core.
+_APPLICATION_NAME_ENV = "ATLAN_APPLICATION_NAME"
+
+#: Owner used when neither a binding nor ``ATLAN_APPLICATION_NAME`` names the app.
+_UNKNOWN_OWNER = "<unknown>"
+
+#: Cap values already reported as invalid, so a bad setting warns once.
+_REPORTED_BAD_CAPS: set[str] = set()
+
+
+@contextlib.contextmanager
+def offload_owner(app_name: str) -> Iterator[None]:
+    """Charge every ``run_in_thread`` call made in this block to *app_name*.
+
+    The binding is a ContextVar, so it is per task and is inherited by tasks
+    created inside the block. An empty *app_name* leaves the fallback in place.
+    """
+    token = _OFFLOAD_OWNER.set(app_name or None)
+    try:
+        yield
+    finally:
+        _OFFLOAD_OWNER.reset(token)
+
+
+def _current_offload_owner() -> str:
+    """The app the current ``run_in_thread`` call is charged to."""
+    bound = _OFFLOAD_OWNER.get()
+    if bound:
+        return bound
+    return os.environ.get(_APPLICATION_NAME_ENV, "").strip() or _UNKNOWN_OWNER
+
+
+def _per_app_cap() -> int | None:
+    """The configured per-app cap, or ``None`` when no cap applies.
+
+    Read on every call so a deployment can change it without a code path that
+    caches a stale value. An unparseable or non-positive value is logged once
+    and ignored rather than raised: raising here would fail every offload in
+    the process over a configuration typo.
+    """
+    raw = os.environ.get(OFFLOAD_MAX_THREADS_PER_APP_ENV, "").strip()
+    if not raw:
+        return None
+    try:
+        cap = int(raw)
+    except ValueError:
+        cap = 0
+    if cap >= 1:
+        return cap
+    if raw not in _REPORTED_BAD_CAPS:
+        _REPORTED_BAD_CAPS.add(raw)
+        logger.warning(
+            "Ignoring %s=%r: expected a positive integer; offloads are not capped "
+            "per app",
+            OFFLOAD_MAX_THREADS_PER_APP_ENV,
+            raw,
+        )
+    return None
+
+
+class _OffloadSlot:
+    """One ``run_in_thread`` call's claim on its app's share of the pool."""
+
+    __slots__ = ("owner", "label", "stranded_at", "finished")
+
+    def __init__(self, owner: str, label: str) -> None:
+        self.owner = owner
+        self.label = label
+        self.stranded_at: float | None = None
+        self.finished = False
+
+
+class _AppOffloadLedger:
+    """Per-app in-flight and stranded counts for the blocking pool. Thread-safe.
+
+    Mutated from the event loop (claim, strand) and from pool threads (the
+    executor future's done callback), hence a ``threading.Lock`` rather than
+    anything asyncio-side.
+    """
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._in_flight: dict[str, int] = {}
+        self._stranded: dict[str, int] = {}
+
+    def claim(self, owner: str, label: str, cap: int | None) -> _OffloadSlot | None:
+        """Take a slot for *owner*; ``None`` if that would exceed *cap*."""
+        with self._lock:
+            held = self._in_flight.get(owner, 0)
+            if cap is not None and held >= cap:
+                return None
+            self._in_flight[owner] = held + 1
+        return _OffloadSlot(owner, label)
+
+    def strand(self, slot: _OffloadSlot) -> int | None:
+        """Record that *slot*'s caller stopped waiting while its thread runs on.
+
+        Returns the owner's stranded count after this one, or ``None`` if the
+        thread had already finished (nothing is stranded).
+        """
+        with self._lock:
+            if slot.finished or slot.stranded_at is not None:
+                return None
+            slot.stranded_at = time.monotonic()
+            count = self._stranded.get(slot.owner, 0) + 1
+            self._stranded[slot.owner] = count
+            return count
+
+    def release(self, slot: _OffloadSlot) -> float | None:
+        """Give *slot* back once its thread is done.
+
+        Returns how long the thread ran after being stranded, or ``None`` if it
+        was never stranded.
+        """
+        with self._lock:
+            if slot.finished:
+                return None
+            slot.finished = True
+            self._in_flight[slot.owner] = self._in_flight.get(slot.owner, 1) - 1
+            if self._in_flight[slot.owner] <= 0:
+                del self._in_flight[slot.owner]
+            if slot.stranded_at is None:
+                return None
+            self._stranded[slot.owner] = self._stranded.get(slot.owner, 1) - 1
+            if self._stranded[slot.owner] <= 0:
+                del self._stranded[slot.owner]
+            return time.monotonic() - slot.stranded_at
+
+    def in_flight(self, owner: str) -> int:
+        with self._lock:
+            return self._in_flight.get(owner, 0)
+
+    def stranded(self) -> dict[str, int]:
+        """A snapshot of every app's stranded count, omitting apps at zero."""
+        with self._lock:
+            return dict(self._stranded)
+
+
+_LEDGER = _AppOffloadLedger()
+
+#: Lazily-created OTel instruments, keyed by name.
+_INSTRUMENTS: dict[str, Any] = {}
+_INSTRUMENTS_LOCK = threading.Lock()
+
+
+def _observe_stranded(_options: Any) -> Iterator[Any]:
+    try:
+        from opentelemetry.metrics import (  # noqa: PLC0415 — only reached from the OTel collection callback
+            Observation,
+        )
+    except ImportError:
+        # Absent on an api-only install; the gauge is never registered there.
+        return
+    for owner, count in _LEDGER.stranded().items():
+        yield Observation(count, {"app.name": owner})
+
+
+def _ensure_stranded_gauge() -> None:
+    """Register the ``offload.stranded_threads`` gauge, once, on the first strand.
+
+    Observable rather than pushed: the count only matters while it is non-zero,
+    and a callback reads the ledger at collection time instead of every strand
+    and release writing a sample. Never raises — telemetry must not turn a
+    cancellation into a different failure.
+    """
+    if "stranded" in _INSTRUMENTS:
+        return
+    with _INSTRUMENTS_LOCK:
+        if "stranded" in _INSTRUMENTS:
+            return
+        try:
+            from opentelemetry import (  # noqa: PLC0415 — cold path: only reached on the first strand
+                metrics as _otel_metrics,
+            )
+
+            _INSTRUMENTS["stranded"] = _otel_metrics.get_meter(
+                "application_sdk.runtime"
+            ).create_observable_gauge(
+                "offload.stranded_threads",
+                callbacks=[_observe_stranded],
+                unit="1",
+                description=(
+                    "run_in_thread calls whose caller stopped waiting (timeout or "
+                    "cancellation) while the thread is still running and holding a "
+                    "blocking-pool slot. Labelled by app; a sustained non-zero value "
+                    "names the app whose blocking calls ignore their own deadlines."
+                ),
+            )
+        except ImportError:
+            # An api-only install has no OpenTelemetry: the strand is still
+            # logged, there is just no gauge.
+            _INSTRUMENTS["stranded"] = None
+        except Exception:
+            _INSTRUMENTS["stranded"] = None
+            logger.debug("Could not register offload.stranded_threads", exc_info=True)
+
+
+def _on_offload_done(slot: _OffloadSlot) -> None:
+    """Executor done callback: release *slot*, reporting a stranded thread's end."""
+    stranded_for = _LEDGER.release(slot)
+    if stranded_for is not None:
+        logger.info(
+            "Stranded offloaded call %s for app %s finished %.1fs after its caller "
+            "stopped waiting; its blocking-pool slot is free again",
+            slot.label,
+            slot.owner,
+            stranded_for,
+        )
+
+
+def _abandon(slot: _OffloadSlot, future: "concurrent.futures.Future[Any]") -> None:
+    """The caller of *future* stopped waiting: cancel it if queued, else record a strand."""
+    if future.cancel():
+        # Still queued: it will never start, and the done callback has already
+        # given the slot back.
+        return
+    if future.done():
+        return
+    count = _LEDGER.strand(slot)
+    if count is None:
+        return
+    _ensure_stranded_gauge()
+    logger.warning(
+        "Offloaded call %s for app %s outlived its caller; the thread keeps a "
+        "blocking-pool slot until the call returns on its own (%d stranded for "
+        "this app). Give the blocking call a driver-level timeout so it returns "
+        "when its caller gives up",
+        slot.label,
+        slot.owner,
+        count,
+    )
+
+
+def _claim_slot(label: str) -> _OffloadSlot:
+    """Claim a slot for the current app, or raise if that app is at its cap."""
+    owner = _current_offload_owner()
+    cap = _per_app_cap()
+    slot = _LEDGER.claim(owner, label, cap)
+    if slot is not None:
+        return slot
+    stranded = _LEDGER.stranded().get(owner, 0)
+    raise ResourceExhaustedError(
+        message=(
+            f"App {owner!r} already has {cap} blocking calls in flight "
+            f"({stranded} stranded past their caller); refusing {label} rather "
+            "than queueing it behind them"
+        ),
+        resource="offload_threads",
+        limit=str(cap),
+        observed=str(_LEDGER.in_flight(owner)),
+        suggested_action=(
+            "Give this app's blocking calls driver-level timeouts so a hung call "
+            f"returns its slot, or raise {OFFLOAD_MAX_THREADS_PER_APP_ENV}."
+        ),
+    )
+
+
 async def run_in_thread(
     func: Callable[..., T],
     *args: Any,
@@ -429,6 +737,18 @@ async def run_in_thread(
       isolated from the caller (copy semantics).
     - Threads run on a dedicated ``sdk-blocking-*`` pool, separate from
       Temporal's activity pool, to avoid deadlocking the worker.
+    - Each call is charged to an app: the handler invocation's app when one is
+      bound (see :func:`offload_owner`), else the process's
+      ``ATLAN_APPLICATION_NAME``. When ``ATLAN_OFFLOAD_MAX_THREADS_PER_APP`` is set,
+      a call that would take its app past that many calls in flight raises a
+      retryable ``ResourceExhaustedError`` at once instead of queueing. Unset,
+      calls queue as they always have. A call counts against its app until its
+      **thread** finishes, not until its caller stops waiting.
+    - A call whose caller stops waiting (timeout, cancellation) while its
+      thread runs on is *stranded*: logged at WARNING with the callable's name
+      and counted per app on the ``offload.stranded_threads`` gauge until the
+      thread returns. A call still queued when its caller stops waiting is
+      cancelled and never starts.
     - The offload is automatically wrapped in an **unbounded** progress hold
       (ADR-0018), so the stall watchdog never accuses a legitimately long
       blocking call of stalling. Nothing to do at the call site, and nothing
@@ -496,15 +816,29 @@ async def run_in_thread(
     if scopes:
         call = _tracked_offload(call, scopes, label)
     cancel_handle = _bound_handle(func)
+    # The app's own pool on the consolidated host (``blocking_executor``), else
+    # the process-wide one.
     executor = _BLOCKING_EXECUTOR_OVERRIDE.get() or _BLOCKING_EXECUTOR
+    # Claimed before the hold opens: an app at its cap fails here at once, with
+    # nothing to unwind (FND-2973).
+    slot = _claim_slot(label)
     with _auto_hold(_THREAD_HOLD_PREFIX + label, None):
-        if cancel_handle is None:
-            return await loop.run_in_executor(executor, call)
         try:
-            return await loop.run_in_executor(executor, call)
+            future = executor.submit(call)
+        except BaseException:
+            # Never submitted (pool shut down at interpreter exit): no thread
+            # will ever release the slot, so release it here.
+            _LEDGER.release(slot)
+            raise
+        # Released when the *thread* is done — see the containment notes above.
+        future.add_done_callback(lambda _done: _on_offload_done(slot))
+        try:
+            return await asyncio.wrap_future(future, loop=loop)
         except asyncio.CancelledError:
-            # Non-blocking: the action is handed to the cancel pool.
-            cancel_handle.request()
+            if cancel_handle is not None:
+                # Non-blocking: the action is handed to the cancel pool.
+                cancel_handle.request()
+            _abandon(slot, future)
             raise
 
 

{atlan_application_sdk_api-3.51.2 → atlan_application_sdk_api-3.52.0}/application_sdk/handler/__init__.py

@@ -20,6 +20,7 @@ from application_sdk.handler.contracts import (
     BaseMetadataConfig,
     CheckTier,
     HandlerCredential,
+    ManifestInput,
     MetadataInput,
     MetadataOutput,
     PreflightCheck,
@@ -69,6 +70,7 @@ __all__ = [
     "HandlerContext",
     "HandlerCredential",
     "HandlerError",
+    "ManifestInput",
     "MetadataInput",
     "MetadataOutput",
     "PreflightCheck",

{atlan_application_sdk_api-3.51.2 → atlan_application_sdk_api-3.52.0}/application_sdk/handler/asgi.py

@@ -15,7 +15,8 @@ shared by every app in the process; handler code is async and offloads through
 
 The metadata routes (configmaps, manifest, input contract) are served from the
 ``generated/`` folder ``gen_app_api.py`` ships inside the app's package
-(:mod:`application_sdk.handler.metadata_routes`). The served manifest's task
+(:mod:`application_sdk.handler.metadata_routes`), through the handler's
+``compute_manifest`` when it overrides that. The served manifest's task
 queue is the one the app's worker polls: its ``ATLAN_TASK_QUEUE`` override when
 the host's app-env sync carries one (``ATLAN_APPENV__<APP>__ATLAN_TASK_QUEUE``),
 else ``derive_task_queue`` over the app's name and its deployment name, read as
@@ -36,12 +37,13 @@ from typing import TYPE_CHECKING, Literal
 from fastapi import FastAPI
 
 from application_sdk._logging import get_logger
-from application_sdk._runtime.offload import blocking_executor
+from application_sdk._runtime.offload import blocking_executor, offload_owner
 from application_sdk.common.task_queue import derive_task_queue
 from application_sdk.handler.base import Handler
 from application_sdk.handler.metadata_routes import (
     MetadataSource,
     generated_dir_of,
+    handler_compute_manifest,
     register_metadata_routes,
 )
 from application_sdk.handler.object_routes import (
@@ -83,7 +85,7 @@ def app_env(app_name: str, key: str, default: str = "") -> str:
 
 @functools.cache
 def default_object_store() -> S3ObjectStore | None:
-    """The host's object store, built once from ``ATLAN_S3_BUCKET`` / ``ATLAN_S3_REGION``.
+    """The host's object store, built once by :meth:`S3ObjectStore.from_env`.
 
     One bucket and one client for every hosted app: each app's configs live
     under its own ``persistent-artifacts/apps/<app>/`` prefix in that bucket.
@@ -173,14 +175,25 @@ def _package_generated_dir(app_package: str) -> Path | None:
 
 
 class _AppBlockingExecutor:
-    """ASGI middleware: ``run_in_thread`` in this app's requests uses its pool."""
+    """ASGI middleware: ``run_in_thread`` in this app's requests uses its pool.
 
-    def __init__(self, app: ASGIApp, executor: concurrent.futures.Executor) -> None:
+    Every request is also charged to ``app_name`` for the per-app offload cap and
+    the stranded-thread count, including the metadata, config and file routes,
+    which run outside a handler context.
+    """
+
+    def __init__(
+        self,
+        app: ASGIApp,
+        executor: concurrent.futures.Executor,
+        app_name: str,
+    ) -> None:
         self.app = app
         self.executor = executor
+        self.app_name = app_name
 
     async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
-        with blocking_executor(self.executor):
+        with blocking_executor(self.executor), offload_owner(self.app_name):
             await self.app(scope, receive, send)
 
 
@@ -210,7 +223,7 @@ def build_asgi_app(
         max_workers=blocking_threads, thread_name_prefix=f"api-{app_name}-"
     )
     app.state.blocking_executor = executor
-    app.add_middleware(_AppBlockingExecutor, executor=executor)
+    app.add_middleware(_AppBlockingExecutor, executor=executor, app_name=app_name)
 
     @app.get("/health")
     async def health() -> dict[str, str]:
@@ -242,6 +255,7 @@ def build_asgi_app(
                 app_package=app_package,
                 task_queue=lambda: _task_queue(app_name, _deployment),
                 deployment_name=_deployment,
+                compute_manifest=handler_compute_manifest(handler, lambda: app_name),
                 from_process_env=False,
             ),
         )

{atlan_application_sdk_api-3.51.2 → atlan_application_sdk_api-3.52.0}/application_sdk/handler/base.py

@@ -12,7 +12,7 @@ from __future__ import annotations
 import warnings
 from abc import ABC, abstractmethod
 from collections.abc import Sequence
-from typing import TYPE_CHECKING, ClassVar
+from typing import TYPE_CHECKING, Any, ClassVar
 
 from application_sdk._context_errors import AppContextError
 from application_sdk.errors import HANDLER_ERROR, ErrorCode
@@ -22,6 +22,7 @@ from application_sdk.handler.contracts import (
     AuthInput,
     AuthOutput,
     AuthStatus,
+    ManifestInput,
     MetadataInput,
     MetadataOutput,
     PreflightInput,
@@ -126,7 +127,8 @@ class Handler(ABC):
             raise AppContextError(
                 "Handler context is not set. "
                 "Access self.context only inside a handler method "
-                "(test_auth, preflight_check, fetch_metadata, warmup)."
+                "(test_auth, preflight_check, fetch_metadata, warmup, "
+                "compute_manifest)."
             )
         return ctx
 
@@ -256,6 +258,30 @@ class Handler(ABC):
         """
         return WarmupObservation(state=WarmupState.READY)
 
+    async def compute_manifest(self, input: ManifestInput) -> dict[str, Any] | None:
+        """The manifest to serve for this request, when it cannot be static.
+
+        Optional. The default returns ``None``, which serves the generated
+        manifest unchanged. Override it for a manifest that depends on the
+        request's ``fe_inputs`` or on the tenant; return ``None`` for an entry
+        point whose generated manifest is right as it is.
+
+        The worker's handler service and the consolidated API host both call
+        it for a request that names an entry point. Task-queue templates in the
+        result (``atlan-<app>-{deployment_name}``) are stamped with the queue
+        the app's worker polls, as in a generated manifest: build them from
+        ``self.context.app_name``. A request carries no credentials here. On
+        the worker an ``app.<segment>.core.compute_manifest`` hook, where one
+        exists, wins; the host never runs one.
+
+        Args:
+            input: The entry point, its generated manifest and the form values.
+
+        Returns:
+            The manifest to serve, or ``None`` for the generated one.
+        """
+        return None
+
 
 class DefaultHandler(Handler):
     """Pass-through handler that always returns SUCCESS/READY/empty.

{atlan_application_sdk_api-3.51.2 → atlan_application_sdk_api-3.52.0}/application_sdk/handler/context.py

@@ -21,6 +21,7 @@ from application_sdk._context_errors import (  # noqa: F401 — AppContextError
 )
 from application_sdk._install import worker_only_missing
 from application_sdk._logging import get_logger
+from application_sdk._runtime.offload import offload_owner
 
 if TYPE_CHECKING:
     from application_sdk.handler.contracts import HandlerCredential
@@ -172,10 +173,15 @@ def bind_handler_context(ctx: HandlerContext) -> Iterator[HandlerContext]:
     (FastAPI requests, Temporal SDR activities) cannot overwrite each other's
     context.  Each asyncio Task gets its own copy of the ContextVar namespace,
     so token-based reset is both safe and strictly scoped to the current task.
+
+    Blocking calls offloaded inside the block are charged to ``ctx.app_name``
+    (FND-2973), so on a pod serving several apps each app's share of the
+    blocking pool is counted and capped separately.
     """
     token = _current_handler_context.set(ctx)
     try:
-        yield ctx
+        with offload_owner(ctx.app_name):
+            yield ctx
     finally:
         _current_handler_context.reset(token)
 

{atlan_application_sdk_api-3.51.2 → atlan_application_sdk_api-3.52.0}/application_sdk/handler/contracts.py

@@ -768,6 +768,20 @@ class WarmupInput(_SourceRequestInput):
     one that does not, and reads the overrun as ``WARMING``."""
 
 
+class ManifestInput(BaseModel):
+    """Input for the optional ``Handler.compute_manifest`` operation."""
+
+    entrypoint: str
+    """The entry point whose manifest is requested."""
+
+    manifest: dict[str, Any]
+    """Its generated manifest, tokens already resolved. Open on purpose: the
+    DAG is a passthrough contract with Automation Engine."""
+
+    fe_inputs: dict[str, Any] = Field(default_factory=dict)
+    """The decoded setup-form values; empty when the request sends none."""
+
+
 class PreflightOutput(BaseModel):
     """Output from the preflight_check handler operation."""
 

{atlan_application_sdk_api-3.51.2 → atlan_application_sdk_api-3.52.0}/application_sdk/handler/metadata_routes.py

@@ -12,11 +12,15 @@ The two surfaces differ only in what a :class:`MetadataSource` resolves:
 
 * the worker resolves entry points from its app registry, stamps the manifest
   with the task queue its own worker polls, and runs an app's
-  ``compute_manifest`` hooks;
+  ``app.<segment>.core.compute_manifest`` hooks;
 * the host has no app registry. It resolves entry points from the generated
-  tree, derives the task queue from the app's name and deployment exactly as the
-  worker does, and serves static manifests only: ``gen_app_api.py check``
-  refuses an app with a ``compute_manifest`` hook, so no hooked app reaches it.
+  tree and derives the task queue from the app's name and deployment exactly as
+  the worker does. It never runs a ``core.py`` hook (``gen_app_api.py check``
+  refuses an app with one).
+
+Both run :meth:`~application_sdk.handler.base.Handler.compute_manifest` when the
+handler overrides it (:func:`handler_compute_manifest`), so a manifest that must
+be computed per request is served the same from either place.
 """
 
 from __future__ import annotations
@@ -28,6 +32,7 @@ from collections.abc import Awaitable, Callable
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any, cast
+from uuid import uuid4
 
 import orjson
 from fastapi import FastAPI, HTTPException, Request
@@ -45,8 +50,17 @@ from application_sdk.common.build_identity import (
     build_identity,
 )
 from application_sdk.common.task_queue import resolve_manifest_tokens
+from application_sdk.errors.base import redact_secrets
+from application_sdk.handler.base import Handler
+from application_sdk.handler.context import (
+    HandlerContext,
+    SecretStore,
+    bind_handler_context,
+)
+from application_sdk.handler.contracts import ManifestInput
 from application_sdk.handler.routes import (
     _ENTRYPOINT_NAME_RE,
+    _http_error_boundary,
     _wrap_response,
     entrypoint_module_segment,
 )
@@ -207,7 +221,7 @@ class MetadataSource:
         input_contract: Resolves ``?entrypoint=`` to its input model, raising
             ``HTTPException``; ``None`` resolves from the generated tree.
         compute_manifest: The entry point's ``compute_manifest`` hook, or
-            ``None``.
+            ``None`` (see :func:`handler_compute_manifest`).
         programmatic_manifest: An ``AppManifest`` built in Python, served when
             no entry point is named.
         log: The logger the routes report through.
@@ -235,6 +249,60 @@ class MetadataSource:
     from_process_env: bool = True
 
 
+def handler_compute_manifest(
+    handler: Handler,
+    app_name: Callable[[], str],
+    *,
+    secret_store: SecretStore | None = None,
+) -> Callable[[str], ComputeManifest | None]:
+    """A ``MetadataSource.compute_manifest`` that runs ``handler.compute_manifest``.
+
+    Resolves to ``None`` for every entry point when the handler does not
+    override it, so such an app is served exactly as before. Otherwise the
+    method runs with a bound :class:`HandlerContext` (no credentials), and a
+    ``None`` result serves the generated manifest.
+    """
+    if type(handler).compute_manifest is Handler.compute_manifest:
+        return lambda _entrypoint: None
+
+    def resolve(entrypoint: str) -> ComputeManifest:
+        async def hook(manifest: dict[str, Any], fe_inputs: dict[str, Any]) -> Any:
+            context = HandlerContext(app_name=app_name(), _secret_store=secret_store)
+            with bind_handler_context(context):
+                try:
+                    computed = await handler.compute_manifest(
+                        ManifestInput(
+                            entrypoint=entrypoint,
+                            manifest=manifest,
+                            fe_inputs=fe_inputs,
+                        )
+                    )
+                except HTTPException as exc:
+                    raise _redacted(exc) from None
+            return manifest if computed is None else computed
+
+        return hook
+
+    return resolve
+
+
+def _redacted(exc: HTTPException) -> HTTPException:
+    """*exc* with its detail passed through :func:`redact_secrets`.
+
+    A handler's ``HTTPException`` is its answer to the caller and keeps its
+    status and message; its detail is scrubbed as an ``AppError`` message is on
+    the other handler routes. A non-string detail is scrubbed as JSON text.
+    """
+    detail = exc.detail if isinstance(exc.detail, str) else orjson.dumps(exc.detail)
+    if isinstance(detail, bytes):
+        detail = detail.decode()
+    return HTTPException(
+        status_code=exc.status_code,
+        detail=redact_secrets(detail),
+        headers=exc.headers,
+    )
+
+
 def register_metadata_routes(app: FastAPI, source: MetadataSource) -> None:
     """Register the configmap, manifest and input-contract routes on *app*."""
 
@@ -508,22 +576,16 @@ def register_metadata_routes(app: FastAPI, source: MetadataSource) -> None:
                 else decode_fe_inputs(fe_inputs, source.max_fe_inputs_bytes())
             )
             manifest_dict = orjson.loads(raw)
-            try:
+            # The other handler routes' boundary: an HTTPException is the
+            # hook's own answer, a typed AppError answers with its category's
+            # status and message, and anything else is a generic 500 whose
+            # internals (stack/SQL/paths) stay in the log.
+            with _http_error_boundary(
+                f"compute_manifest for entrypoint {entrypoint_name!r}",
+                source.app_name(),
+                str(uuid4()),
+            ):
                 computed = await compute(manifest_dict, fe_inputs_decoded)
-            except HTTPException:
-                raise
-            except Exception:
-                # Don't leak the hook's internals (stack/SQL/paths) to the
-                # caller — mirror the other handler routes' generic 500.
-                # conformance: ignore[L009] boundary handler logs the real exception (exc_info) then raises a sanitized HTTPException `from None`; the log is the only server-side record of the actual failure.
-                log.error(
-                    "compute_manifest hook failed for entrypoint %r",
-                    entrypoint_name,
-                    exc_info=True,
-                )
-                raise HTTPException(
-                    status_code=500, detail="Internal server error"
-                ) from None
             if not isinstance(computed, dict):
                 # conformance: ignore[L009] logs caller-invisible context (the actual returned type) that the generic 500 HTTPException detail omits.
                 log.error(

{atlan_application_sdk_api-3.51.2 → atlan_application_sdk_api-3.52.0}/application_sdk/handler/object_routes.py

@@ -12,8 +12,9 @@ consolidated API host register the same routes through
 * the worker uses its Dapr-configured ``application_sdk.storage`` store;
 * the host has no Dapr, so it uses :class:`S3ObjectStore`, configured from the
   chart-injected ``ATLAN_S3_BUCKET`` / ``ATLAN_S3_REGION`` with the pod's ambient AWS
-  identity (the ``aws`` extra). Without ``ATLAN_S3_BUCKET`` the routes answer 503,
-  exactly as the worker does without a store.
+  identity (the ``aws`` extra), or on GCP from ``ATLAN_GCP_BUCKET`` (aliasing the
+  chart's ``GCP_BUCKET``) through GCS's S3-compatible API. Without a bucket the routes answer 503, exactly as the
+  worker does without a store.
 
 Both write a config to ``persistent-artifacts/apps/{app_name}/{type}/{id}/config.json``.
 On the host ``app_name`` is the hosted app's name, never the host's own, so the
@@ -315,14 +316,30 @@ class S3Client(Protocol):
     def upload_file(self, filename: str, bucket: str, key: str, /) -> None: ...
 
 
+#: GCS's S3-compatible (XML API) endpoint.
+_GCS_ENDPOINT = "https://storage.googleapis.com"
+
+
+def _resolved_env(name: str) -> str:
+    """``name``'s value, or ``""`` when unset or an unresolved Kubernetes alias.
+
+    The host's manifest aliases chart names (``ATLAN_S3_BUCKET: "$(S3_BUCKET)"``);
+    where the chart does not inject the source, Kubernetes leaves the
+    ``$(...)`` text in place, which is no value, not a bucket or region.
+    """
+    value = os.environ.get(name, "").strip()
+    return "" if value.startswith("$(") else value
+
+
 class S3ObjectStore:
     """One S3 bucket through a boto3 client: the host's store.
 
-    Auth is ambient (node role / IRSA / env), exactly as the fleet's Dapr
+    On AWS auth is ambient (node role / IRSA / env), exactly as the fleet's Dapr
     ``bindings.aws.s3`` components authenticate: their specs carry only a
-    bucket and a region. No credential value is read here. boto3 calls run on
-    the app's own ``run_in_thread`` pool, so S3 latency never blocks the host's
-    event loop.
+    bucket and a region. On GCP the bucket is GCS, reached with the chart's HMAC
+    keys (:meth:`from_env`); they go to boto3 and are never logged. boto3 calls
+    run on the app's own ``run_in_thread`` pool, so S3 latency never blocks the
+    host's event loop.
     """
 
     def __init__(
@@ -337,12 +354,19 @@ class S3ObjectStore:
 
     @classmethod
     def from_env(cls) -> S3ObjectStore | None:
-        """From ``ATLAN_S3_BUCKET`` / ``ATLAN_S3_REGION``; ``None`` when no bucket is set."""
-        bucket = os.environ.get("ATLAN_S3_BUCKET", "").strip()
+        """From ``ATLAN_S3_BUCKET`` / ``ATLAN_S3_REGION``, or on GCP from
+        ``ATLAN_GCP_BUCKET`` (:meth:`_gcs_from_env`); ``None`` when no bucket is set."""
+        gcs_bucket = _resolved_env("ATLAN_GCP_BUCKET")
+        if gcs_bucket:
+            # First: the chart injects no S3_* on GCP, so the host's ATLAN_S3_*
+            # aliases are unresolved there.
+            return cls._gcs_from_env(gcs_bucket)
+        # Azure Blob tenants get no S3_* either: no bucket (Blob is not served yet).
+        bucket = _resolved_env("ATLAN_S3_BUCKET")
         if not bucket:
             return None
         try:
-            return cls(bucket, os.environ.get("ATLAN_S3_REGION", "").strip() or None)
+            return cls(bucket, _resolved_env("ATLAN_S3_REGION") or None)
         except ModuleNotFoundError:
             logger.warning(
                 "ATLAN_S3_BUCKET is set but boto3 is not installed, so the config and "
@@ -351,6 +375,46 @@ class S3ObjectStore:
             )
             return None
 
+    @classmethod
+    def _gcs_from_env(cls, bucket: str) -> S3ObjectStore | None:
+        """GCS through its S3-compatible API, with the tenant's HMAC key pair.
+
+        The host's manifest aliases the atlan-app chart's GCP-only ``GCP_*``
+        names as ``ATLAN_GCP_*``; elsewhere they are unresolved, so unset.
+        """
+        access_key = _resolved_env("ATLAN_GCP_HMAC_ACCESS_KEY")
+        secret = _resolved_env("ATLAN_GCP_HMAC_SECRET")
+        if not (access_key and secret):
+            logger.warning(
+                "ATLAN_GCP_BUCKET is set without ATLAN_GCP_HMAC_ACCESS_KEY / "
+                "ATLAN_GCP_HMAC_SECRET, so the config and file routes answer 503."
+            )
+            return None
+        try:
+            import boto3  # noqa: PLC0415 — the aws extra; loaded only when GCS is configured
+            from botocore.config import Config  # noqa: PLC0415 — ships with boto3
+        except ModuleNotFoundError:
+            logger.warning(
+                "ATLAN_GCP_BUCKET is set but boto3 is not installed, so the config and "
+                "file routes answer 503. Install atlan-application-sdk-api[aws].",
+                exc_info=True,
+            )
+            return None
+        client = boto3.client(
+            "s3",
+            endpoint_url=_GCS_ENDPOINT,
+            region_name=_resolved_env("ATLAN_GCP_REGION") or None,
+            aws_access_key_id=access_key,
+            aws_secret_access_key=secret,
+            # boto3 >= 1.36 sends CRC32 checksums (aws-chunked uploads, checksum
+            # mode on reads) that GCS rejects: boto/boto3#4400.
+            config=Config(
+                request_checksum_calculation="when_required",
+                response_checksum_validation="when_required",
+            ),
+        )
+        return cls(bucket, client=cast("S3Client", client))
+
     async def get_json(self, key: str) -> dict[str, Any] | None:
         """The object at ``key``, or ``None`` when it is missing.
 

{atlan_application_sdk_api-3.51.2 → atlan_application_sdk_api-3.52.0}/application_sdk/version.py

@@ -36,5 +36,5 @@ only to reconcile ahead of a release — and deliberately, since older Dapr
 releases drop off the CDN.
 """
 
-__version__ = "3.51.2"
+__version__ = "3.52.0"
 __dapr_version: str = "1.18.7"

{atlan_application_sdk_api-3.51.2 → atlan_application_sdk_api-3.52.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "atlan-application-sdk-api"
-version = "3.51.2"
+version = "3.52.0"
 description = "Experimental: the handler surface of the Atlan Application SDK, for the consolidated API host"
 license = "Apache-2.0"
 authors = [