Merge branch 'main' into SEP-1936

Author: yyyyyyyan

app/sep/apps/atw/api_routes.py

@@ -34,6 +34,7 @@
 from app.core.pagination import PaginatedResponse
 from app.core.pagination.deps import PaginationDep
 from app.core.utils.date_time import utc_now
+from app.core.utils.fields import StrippedNonEmptyStr
 from app.core.utils.iterators import unique_everseen
 from app.sep.apps.atw.batch import (
     ATWBatchExecuteItemResponse,
@@ -65,11 +66,14 @@
     AtwIncidentDep,
     AtwSnippetSearchQueryDep,
     ClosedAtwIncidentDep,
+    diagnostics_case_search_available,
     diagnostics_send_disabled_reasons,
     IsDiagnosticsSendConfigured,
     OpenAtwIncidentDep,
 )
 from app.sep.apps.atw.models import (
+    AtwCaseMatch,
+    AtwCaseSearchResponse,
     AtwConfigResponse,
     AtwIncident,
     AtwIncidentExecution,
@@ -83,7 +87,9 @@
 )
 from app.sep.apps.atw.schema import atw_schema
 from app.sep.apps.framework.api import schema_endpoint
-from app.sep.deps import ApiCurrentUser, SessionDep, TaskAPI
+from app.sep.bundle_upload.factory import get_delivery_executor
+from app.sep.bundle_upload.resolver import resolve_delivery_plan
+from app.sep.deps import ApiCurrentUser, IsApiAdmin, SessionDep, TaskAPI
 from app.sep.snippets.crud import SnippetManager
 from app.sep.snippets.masking import mask_snippet_args
 from app.sep.snippets.models import Snippet
@@ -105,6 +111,23 @@
 NO_TASK_ID_ERROR = "Dispatched, but the Tasks API returned no task id; not recorded."
 UNRECORDED_EXECUTION_ERROR = "Dispatched, but the execution row could not be recorded"
 
+#: How long a case search may take before the field falls back to free text.
+#: Deliberately far below the delivery probe's 15s and the intra-cluster 5s:
+#: those bound a one-off operator action, while this is issued while someone is
+#: still typing. ``RemoteAPI`` carries only a session-level timeout
+#: (``sock_read=120``), so this is what actually bounds the call.
+CASE_SEARCH_TIMEOUT_SECONDS = 3
+
+#: The longest search term the route forwards to the receiver. A case reference
+#: or a title fragment is far shorter; the cap is what keeps an arbitrary string
+#: out of the provider's query.
+MAX_CASE_SEARCH_TERM_LENGTH = 128
+
+#: The most matches the route offers the dialog. ``CaseSearchStep`` declares no
+#: limit of its own, so without this the response's cardinality is whatever the
+#: receiver returns.
+MAX_CASE_SEARCH_MATCHES = 25
+
 
 class ATWSnippetSummary(BaseModel):
     """Represent one snippet entry under an ATW category.
@@ -628,12 +651,68 @@ def _build_execution_response(
 async def atw_config() -> AtwConfigResponse:
     """Report whether the incident send action is available.
 
-    Not gated by the send guard -- this endpoint is what reports that guard, so
+    Not gated by the send guard: this endpoint is what reports that guard, so
     it must answer whether or not a receiver is configured.
 
-    :return: The reasons the send action is withheld; empty when it is offered.
+    :return: The reasons the send action is withheld, and whether the
+        case-reference field may search the receiver.
     """
-    return AtwConfigResponse(send_disabled_reasons=diagnostics_send_disabled_reasons())
+    return AtwConfigResponse(
+        send_disabled_reasons=diagnostics_send_disabled_reasons(),
+        case_search_available=diagnostics_case_search_available(),
+    )
+
+
+@router.get("/case-search/", dependencies=[IsApiAdmin])
+async def atw_case_search(
+    term: Annotated[
+        StrippedNonEmptyStr,
+        Query(
+            max_length=MAX_CASE_SEARCH_TERM_LENGTH,
+            description="The support case reference or title fragment to match.",
+        ),
+    ],
+) -> AtwCaseSearchResponse:
+    """Search the configured delivery provider for support cases matching ``term``.
+
+    No way the search itself can fail reaches the caller as an error: a
+    deployment that declares no case-search section, stored inputs that no
+    longer fit the plan, a refused credential, an unreachable receiver and a
+    search that outran its bound all report the same unavailability, which the
+    caller renders as the plain text field rather than as a search that found
+    nothing.
+
+    Restricted to administrators, unlike the app's other reads. The router
+    resolves a minimum role for unsafe methods only, so a safe method carries
+    whatever guard it declares itself; this one issues the deployment's own
+    receiver credential, and the dialog that calls it is already offered to
+    administrators alone.
+
+    :param term: The caller's typed search term, the only input it accepts.
+        Surrounding whitespace is stripped, so a whitespace-only term is
+        refused rather than reaching the receiver as a match-everything
+        fragment.
+    :return: The matched cases, or that the search could not run. At most
+        ``MAX_CASE_SEARCH_MATCHES`` are offered, so a plan that declares no
+        provider-side limit still cannot hand the dialog an unbounded list.
+    """
+    plan = resolve_delivery_plan().plan
+    if plan is None or plan.case_search is None:
+        return AtwCaseSearchResponse(available=False, matches=[])
+    try:
+        async with asyncio.timeout(CASE_SEARCH_TIMEOUT_SECONDS):
+            async with get_delivery_executor(plan) as executor:
+                matches = await executor.search_cases(term)
+    except Exception:  # noqa: BLE001 -- degraded, never surfaced to the dialog
+        logger.warning("Diagnostics case search failed.", exc_info=True)
+        return AtwCaseSearchResponse(available=False, matches=[])
+    return AtwCaseSearchResponse(
+        available=True,
+        matches=[
+            AtwCaseMatch(reference=match.reference, title=match.title)
+            for match in matches[:MAX_CASE_SEARCH_MATCHES]
+        ],
+    )
 
 
 async def _resolve_selected_executions(

app/sep/apps/atw/deps.py

@@ -94,6 +94,19 @@ def diagnostics_send_disabled_reasons() -> list[str]:
     return []
 
 
+def diagnostics_case_search_available() -> bool:
+    """Report whether this deployment can search the receiver for cases.
+
+    Distinct from the send gate: delivery may be fully configured while the plan
+    declares no case-search section, in which case the case-reference field
+    stays the plain text input it has always been.
+
+    :return: Whether a case search can be issued.
+    """
+    resolution = resolve_delivery_plan()
+    return resolution.plan is not None and resolution.plan.case_search is not None
+
+
 async def require_diagnostics_send_configured() -> None:
     """Raise if diagnostics delivery is not configured.
 

app/sep/apps/atw/models.py

@@ -276,11 +276,41 @@ class AtwSendLogResponse(BaseModel):
     detail: dict[str, Any] = Field(json_schema_extra=ARBITRARY_ARGS_SCHEMA)
 
 
+class AtwCaseMatch(BaseModel):
+    """Represent one support case the delivery provider matched.
+
+    :param reference: The case reference to send diagnostics against.
+    :param title: The case title, shown beside the reference to tell two
+        similar references apart.
+    """
+
+    reference: str
+    title: str
+
+
+class AtwCaseSearchResponse(BaseModel):
+    """Report the cases matching a typed term, or that the search could not run.
+
+    :param available: Whether the search ran at all. This is what keeps an
+        unavailable search distinct from an available one that matched nothing:
+        a caller must not render the first as the second.
+    :param matches: The matched cases, empty when there are none and when the
+        search could not run.
+    """
+
+    available: bool
+    matches: list[AtwCaseMatch]
+
+
 class AtwConfigResponse(BaseModel):
     """Report whether the incident send action is available.
 
     :param send_disabled_reasons: Why sending is unavailable; empty when the
         receiver is configured and the action is offered.
+    :param case_search_available: Whether the case-reference field may query the
+        receiver for matches. Defaults to ``False`` so a client built against
+        the response before this field existed keeps validating.
     """
 
     send_disabled_reasons: list[str]
+    case_search_available: bool = False

app/sep/bundle_upload/factory.py

@@ -30,10 +30,10 @@
 
 from app.core.requests import RemoteAPI
 from app.sep.bundle_upload.plan import (
+    AnyStepValue,
     DeliveryPlan,
     DeliveryPlanExecutor,
     LiteralValue,
-    PlanValue,
     StepObserver,
 )
 
@@ -69,13 +69,13 @@ def _rebase_path(prefix: str, path: str) -> str:
 
 
 def _rebase_query(
-    query: Mapping[str, PlanValue], endpoint_query: dict[str, str]
-) -> dict[str, PlanValue]:
+    query: Mapping[str, AnyStepValue], endpoint_query: dict[str, str]
+) -> dict[str, AnyStepValue]:
     """Merge the endpoint's query pairs into a step's own, without displacing them.
 
-    Accepts any value map the plan admits, so a step whose values are drawn
-    from a narrower set than :data:`~app.sep.bundle_upload.plan.PlanValue`,
-    as the probe's are, rebases through the same helper.
+    Accepts any value map any step kind admits, so one helper rebases them all:
+    the probe's, drawn from a set narrower than the send steps', and the case
+    search's, carrying a source the send steps have no value for.
 
     :param query: The step's configured query map.
     :param endpoint_query: The query pairs carried by the configured endpoint.
@@ -132,8 +132,23 @@ def _rebased_plan(
             }
         )
     )
+    case_search = (
+        None
+        if plan.case_search is None
+        else plan.case_search.model_copy(
+            update={
+                "path": _rebase_path(path, plan.case_search.path),
+                "query": _rebase_query(plan.case_search.query, query),
+            }
+        )
+    )
     return plan.model_copy(
-        update={"resolution_steps": steps, "upload": upload, "probe": probe}
+        update={
+            "resolution_steps": steps,
+            "upload": upload,
+            "probe": probe,
+            "case_search": case_search,
+        }
     )