48 lines
2.4 KiB
Markdown
48 lines
2.4 KiB
Markdown
# Shared research API (in progress)
|
||
|
||
This work belongs to Thesisly 研迹 and uses Foundry Core rather than a separate
|
||
application backend. The corpus is public; account sessions and future private
|
||
collections remain project scoped.
|
||
|
||
## Current implementation boundary
|
||
|
||
`internal/research` implements the HTTP contract and repository boundary. It is
|
||
not registered by `cmd/foundry` yet and does not open any database connection.
|
||
The existing SQLite implementation was withdrawn. Wait for the separate Paper
|
||
Atlas PostgreSQL migration to finish, inspect the published schema and indexes,
|
||
then implement the repository with a least-privilege read-only connection and
|
||
register it in the existing server. Do not add `FOUNDRY_RESEARCH_DATABASE`.
|
||
|
||
## Routes
|
||
|
||
- `GET /projects/{project}/research/papers`
|
||
- `GET /projects/{project}/research/papers/{id}`
|
||
|
||
Only configured Foundry projects are accepted. Reading the public corpus does
|
||
not require a session; these routes do not expose private data or accept writes.
|
||
|
||
List parameters are `q` (200 Unicode characters, 20 words), `searchIn`
|
||
(`text` or `author`), `topic` (an exact arXiv category), `sort` (`recent` or
|
||
`title`), `page` (1–1000), and `pageSize` (1–50, default 8). Unknown, malformed
|
||
or repeated parameters return 400. `recent` means descending stable paper ID,
|
||
not publication date. Search terms must become bound query parameters, never
|
||
raw SQL or user-supplied full-text syntax.
|
||
|
||
List responses contain `items`, `total`, `topics`, `page`, and `pageSize`.
|
||
Each paper preserves original title/abstract, authors, source dates, topics and
|
||
source links. Publication decisions need source evidence; absent decisions stay
|
||
unknown. No invented repositories, metrics or generated research conclusions.
|
||
|
||
The repository must count and read each list in one read-only snapshot. The
|
||
HTTP layer permits two in-flight queries with an eight-second context budget.
|
||
Busy requests return 429 with `Retry-After: 1`; deadlines return 504; storage
|
||
errors return a generic 503 without database details. Missing papers return 404.
|
||
|
||
## Validation
|
||
|
||
`go test -race -count=1 ./internal/research` covers routing, query limits,
|
||
Unicode, anonymous reads, rejected mutations, project lookup, errors, saturation
|
||
and timeout slot release. Run compilation/tests only on the user-confirmed ECS
|
||
runner. These transport tests do not prove a database connection, full-corpus
|
||
query performance or production availability.
|