106 lines
4.6 KiB
Markdown
106 lines
4.6 KiB
Markdown
# PR#25: the statistics are public, only the recent reviews need a read token
|
|
|
|
> **WARNING:** This document describes only the change applied in this PR.
|
|
> It may already be outdated once the next PR is merged.
|
|
> Historic PR documentation is not maintained along with new PRs; treat it as a snapshot.
|
|
|
|
## The Problem
|
|
|
|
The dashboard of werkrevisor 0.18.3 shows the sums per repository, per model and per verdict only with a read token.
|
|
Most of these sums tell nothing that the operator wants to hide, and the costs per model are the point of the dashboard.
|
|
So each viewer needs a token for data that is not secret.
|
|
|
|
Two parts are different:
|
|
|
|
- The list of recent reviews links single pull requests.
|
|
- The name of a private repository is content of that repository.
|
|
|
|
## Non-Goals
|
|
|
|
- No change of the source tokens or of `POST /api/usage` and `POST /api/billed-calls`.
|
|
- No per-viewer rights: a read token still shows all recent reviews and all repository names.
|
|
- No query of Gitea by the service: the review run reports whether its repository is private.
|
|
|
|
## The Scenarios
|
|
|
|
### Feature: the sums are public
|
|
|
|
#### Scenario#25.01: the sums per repository, model and verdict need no token
|
|
|
|
So that anybody can see what werkrevisor costs and how it judges.
|
|
|
|
- **Given** two repositories reported reviews
|
|
- **When** someone opens the dashboard without a token
|
|
- **Then** the dashboard shows the tables "by repository", "by verdict" and "by model"
|
|
- **and** no value links a single pull request
|
|
|
|
##### Verified by
|
|
|
|
- [UsageApiIntegrationTest: sums per repository, model and verdict without a token](../../server/src/test/kotlin/de/hoennig/werkrevisor/server/UsageApiIntegrationTest.kt)
|
|
- manual check in a browser, see [Measurement](#measurement)
|
|
|
|
### Feature: the recent reviews stay protected
|
|
|
|
#### Scenario#25.02: the recent reviews need a read token
|
|
|
|
So that the links to single pull requests of private repositories stay hidden.
|
|
|
|
- **Given** two repositories reported reviews
|
|
- **When** someone opens the dashboard `<with>`
|
|
- **Then** the list "Recent reviews" `<shows>`
|
|
|
|
| with | shows |
|
|
|---|---|
|
|
| no token | is missing |
|
|
| a wrong token | is missing |
|
|
| a source token | is missing |
|
|
| a read token | shows both reviews |
|
|
|
|
##### Verified by
|
|
|
|
- [UsageApiIntegrationTest: recent reviews only with a read token](../../server/src/test/kotlin/de/hoennig/werkrevisor/server/UsageApiIntegrationTest.kt)
|
|
|
|
#### Scenario#25.03: a private repository is named only with a read token
|
|
|
|
So that the dashboard does not reveal the name of a private repository.
|
|
|
|
- **Given** the newest review of a repository reported it as `<visibility>`
|
|
- **When** someone opens the dashboard without a token
|
|
- **Then** the table "by repository" `<shows>`
|
|
|
|
| visibility | shows |
|
|
|---|---|
|
|
| public | the name of the repository |
|
|
| private | its costs in the line "private repositories" |
|
|
| unknown, from a run before werkrevisor 0.18.4 | its costs in the line "private repositories" |
|
|
| private, after an earlier review reported it as public | its costs in the line "private repositories" |
|
|
| unknown, after an earlier review reported it as public | its costs in the line "private repositories" |
|
|
|
|
##### Verified by
|
|
|
|
- [UsageApiIntegrationTest: private repositories are named only with a read token](../../server/src/test/kotlin/de/hoennig/werkrevisor/server/UsageApiIntegrationTest.kt)
|
|
- [test_stats_client: test_a_private_repository_is_reported_as_such](../../tests/test_stats_client.py)
|
|
- [test_stats_client: test_a_missing_or_odd_private_flag_is_reported_as_unknown](../../tests/test_stats_client.py),
|
|
for a missing repository, a missing flag and a flag that is no boolean
|
|
|
|
## The Solution
|
|
|
|
- `GET /api/stats` always returns `details`; `details.recent` is `null` without a read token.
|
|
- The usage record holds `repo_private`, the flag of the base repository from Gitea's pull request.
|
|
Without a read token, the table per repository sums each repository whose newest record is not public
|
|
in the line "private repositories".
|
|
Old records have no flag; their repositories show by name after the next run with werkrevisor 0.18.4.
|
|
- The Web Component always shows the tables per repository, verdict and model, and the recent reviews if it gets them.
|
|
- The start page asks for a "read token for recent reviews".
|
|
- werkrevisor 0.18.4.
|
|
|
|
## Measurement
|
|
|
|
On 2026-10-06, the service ran locally with a copy of the live database.
|
|
Without a token, the dashboard showed the tables per day, week, month, repository, verdict and model, but no recent reviews;
|
|
with the read token it added "Recent reviews" with all 10 reviews of the copy.
|
|
|
|
## Prerequisite PRs
|
|
|
|
- PR#24: billed OpenRouter calls.
|