47 lines
1.5 KiB
Markdown
47 lines
1.5 KiB
Markdown
|
# Pagination Adoption — hub-core utils in Core Hub
|
|||
|
|
|
|||
|
|
**Updated:** 2026-07-09
|
|||
|
|
**Workplan:** `CORE-WP-0009-T05`
|
|||
|
|
**Decision:** Defer DB pagination; document trigger for adoption
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Current state
|
|||
|
|
|
|||
|
|
Core Hub `/api/v2` list endpoints (`hubs`, `hub-capability-manifests`,
|
|||
|
|
`api-consumers`, `widgets`, `interaction-events`) load full result sets and wrap
|
|||
|
|
them with an in-memory helper:
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
def page(data: list[dict[str, Any]]) -> dict[str, Any]:
|
|||
|
|
return {"data": data, "count": len(data)}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Production table counts remain small (bootstrap/smoke scale). Inter-Hub
|
|||
|
|
compatibility fixtures expect `{data, count}` without `limit`/`offset` query
|
|||
|
|
params today.
|
|||
|
|
|
|||
|
|
## hub-core utility
|
|||
|
|
|
|||
|
|
`hub_core.utils.pagination` provides sync SQLAlchemy `PageParams` and
|
|||
|
|
`apply_pagination()` for `Select` queries. Core Hub uses **async**
|
|||
|
|
SQLAlchemy (`AsyncSession.execute(select(...))`).
|
|||
|
|
|
|||
|
|
## Decision
|
|||
|
|
|
|||
|
|
**Defer adoption** until either:
|
|||
|
|
|
|||
|
|
1. A list endpoint needs server-side `limit`/`offset` (or cursor) for performance, or
|
|||
|
|
2. Inter-Hub compatibility spec adds optional pagination query parameters.
|
|||
|
|
|
|||
|
|
When triggered:
|
|||
|
|
|
|||
|
|
- Add `hub_core.utils.pagination_async` (or equivalent) with the same bounds as
|
|||
|
|
`PageParams` (limit 1–1000, offset ≥ 0).
|
|||
|
|
- Apply to list routes before `session.execute`.
|
|||
|
|
- Extend contract fixtures and ops-hub smokes for paginated responses.
|
|||
|
|
|
|||
|
|
## Non-action
|
|||
|
|
|
|||
|
|
Do not import sync `apply_pagination` into async routes without an async adapter.
|
|||
|
|
Do not change response shape until compatibility spec records the addition.
|