app.routers.records

HTTP routes for searching and viewing catalog records.

Thin: query-parameter validation and status codes only; all assembly logic lives in app.services.search and app.services.record_detail. These routes only use the storage provider (app.composition.get_store_provider()) and the catalog configuration loaded at startup (app.composition.get_catalog_runtime()) – never a source adapter, so normal browse/search requests make no source calls (see docs/developer/decisions/0004-reads-from-local-index.rst).

app.routers.records.list_records(q=Query(None), source=Query(None), project=Query(None), state=Query(None), needs_approval=Query(False), record_type=Query(decision), sort=Query(None), page=Query(1), page_size=Query(20), provider=Depends(dependency=<function get_store_provider>, use_cache=True, scope=None), runtime=Depends(dependency=<function get_catalog_runtime>, use_cache=True, scope=None))

Search the catalog with the Phase 1 filters.

Parameters:

  • q (str | None) – Free text (titles, bodies, UUIDs, paths); blank or omitted matches everything.

  • source (str | None) – Restrict to one registration id.

  • project (str | None) – Restrict to one project path.

  • state (RecordState | None) – Restrict to published or candidate.

  • needs_approval (bool) – Restrict to records that need approval.

  • record_type (RecordTypeFilter) – Decisions (default), errata, or both.

  • sort (SearchSort | None) – Result order, or omitted for the default.

  • page (int) – 1-based page number.

  • page_size (int) – Page size, 1 to MAX_PAGE_SIZE.

  • provider (CatalogStoreProvider) – Storage provider (overridden by tests).

  • runtime (CatalogRuntime | None) – Startup configuration state.

Return type:

SearchPageOut

Returns:

The page.

app.routers.records.get_record(record_id, provider=Depends(dependency=<function get_store_provider>, use_cache=True, scope=None), runtime=Depends(dependency=<function get_catalog_runtime>, use_cache=True, scope=None), settings=Depends(dependency=<functools._lru_cache_wrapper object>, use_cache=True, scope=None), principal=Depends(dependency=<function require_permission.<locals>._check>, use_cache=True, scope=None))

Fetch one record’s detail page.

approval.can_decide (and the blocked reason) is evaluated for the caller.

Parameters:

  • record_id (UUID) – Record id.

  • provider (CatalogStoreProvider) – Storage provider (overridden by tests).

  • runtime (CatalogRuntime | None) – Startup configuration state.

  • settings (Settings) – Application settings (for the stale threshold).

  • principal (Principal) – The authenticated caller.

Return type:

RecordDetailOut

Returns:

The detail.

Raises:

app.errors.NotFoundError – If the record does not exist.

app.routers.records.get_record_diff(record_id, from_digest=Query(None), to_digest=Query(None), provider=Depends(dependency=<function get_store_provider>, use_cache=True, scope=None))

Diff two stored snapshots of the record’s identity.

Only digests related to the record are accepted (404 unknown_revision otherwise); see app.services.diff.

Parameters:

  • record_id (UUID) – Record id.

  • from_digest (str | None) – Base digest (query from).

  • to_digest (str | None) – Target digest (query to).

  • provider (CatalogStoreProvider) – Storage provider (overridden by tests).

Return type:

RecordDiffOut

Returns:

The diff, or base: null with reason: "no_prior_revision".