Metadata-Version: 2.4
Name: splent_feature_spl_registry
Version: 0.6.2
License-Expression: LGPL-3.0-or-later
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: COPYING
License-File: COPYING.LESSER
Requires-Dist: splent_framework>=1.30.0
Requires-Dist: requests>=2.31
Dynamic: license-file

# splent_feature_spl_registry

The marketplace's registry of software product lines. It owns which SPLs exist,
who owns each one, the DOI pointer to the published UVL model, and the relay
that publishes a model to UVLHub.

Each line's name, description and `{mirror, doi, file}` pointer live in the
`spl` table, and `GET /api/v1/spls` serves them to the splent CLI and to the
job that builds the marketplace index.

## The model

```
developer --(splent CLI with a splent token)--> MARKETPLACE --(one server-side key)--> UVLHub
```

A developer authenticates to the marketplace with a token from
`splent_feature_apikeys` and sends a `.uvl` file. They never hold UVLHub
credentials, never name a UVLHub dataset and never learn UVLHub is involved.
The marketplace validates the model, relays it with its single key, and stores
the DOI pointer. The UVL content itself is never stored here.

Publishing a FEATURE is unchanged: `splent feature:release`, no account, no
token, the git tag is the publication. This feature is only about product
lines.

## Ordering

A release row is written **before** the irreversible call to UVLHub, then
updated with the outcome. This is the point of the design. If the publish call
times out and nothing was written down first, the marketplace cannot tell
whether a DOI was minted, and the honest answer ("I do not know") gets replaced
by the tempting one ("try again"), which mints a second permanent DOI for the
same model.

A release is `reserved` while it is being published, and settles into one of
three states. Sending the same bytes again never mints a second DOI, whatever
the state:

| state       | meaning                                    | the same bytes sent again |
|-------------|--------------------------------------------|---------------------------|
| `published` | UVLHub minted a DOI, recorded here         | answered with that DOI |
| `failed`    | UVLHub refused. Nothing was minted         | sent again |
| `unknown`   | No answer after the irreversible call      | looked for on UVLHub first, answered with its DOI once found, refused until then |

A 5xx on the call that mints is `unknown`, not `failed`. A proxy in front of
UVLHub answers 504 when it stops waiting, while UVLHub carries on and mints.

Settlements are conditional updates. Whichever of the publication and the
search below settles a release second never erases what the first learned. A
late timeout never overwrites a DOI, and a DOI from UVLHub lands over a guess.

## Answering at once, and finding a mint that lost track

Minting a DOI waits on Zenodo, and a new version is six Zenodo calls in a row,
which can take minutes. A client that sends `Prefer: respond-async` gets `202`
as soon as the release is reserved, with a `Location` to follow it at, and the
relay runs in a thread with an application context of its own. A client that
does not ask gets the answer it always got, once the DOI exists. `splent
spl:publish` asks, and follows the release until it settles.

A release nobody knows the outcome of, `unknown` or `reserved` for longer than
any call could take, is looked for on UVLHub. The registry walks the versions
of the line's dataset, downloads every DOI the line does not hold yet, and
settles the release as `published` only when the bytes UVLHub serves hash to
the sha256 recorded at reservation. Nothing short of that settles it. It looks
when the release's owner asks about it (in the background, at most once a
minute), when the same model is sent again, and when an administrator runs
`splent feature:spl_registry reconcile`. `settle` is left for the rare release
whose bytes UVLHub never serves.

Only one release of a line is published at a time. Each version is minted on
top of the one before, so a second model sent meanwhile is refused with `409`.

## Endpoints

| method | path                            | auth               |
|--------|---------------------------------|--------------------|
| GET    | `/api/v1/spls`                  | public             |
| GET    | `/api/v1/spls/<name>`           | public             |
| POST   | `/api/v1/spls/<name>/releases`  | Bearer, `write_spl` |
| GET    | `/api/v1/spls/<name>/releases/<version>` | Bearer, `write_spl`, the line's owner |
| GET    | `/marketplace/spls/<name>`      | public page        |

```bash
curl -X POST https://<marketplace>/api/v1/spls/my_line/releases \
     -H "Authorization: Bearer splent_..." \
     -H "Prefer: respond-async" \
     -F "file=@my_line.uvl"
# 202, Location: /api/v1/spls/my_line/releases/3

curl https://<marketplace>/api/v1/spls/my_line/releases/3 \
     -H "Authorization: Bearer splent_..."
# {"state": "published", "doi": "10.5281/zenodo...", ...}
```

## Configuration

Every variable has a working default; the feature runs with no `.env` entry.

| variable                             | default                  | what it does |
|--------------------------------------|--------------------------|--------------|
| `UVLHUB_API_KEY`                     | (none)                   | the single server-side key. Without it the write path answers 503 |
| `UVLHUB_URL`                         | `https://www.uvlhub.io`  | which instance to relay to |
| `SPL_REGISTRY_PUBLISHING_ENABLED`    | `false`                  | the arming switch. Publishing answers 503 until a deployment turns it on, and every read path stays up either way |
| `SPL_REGISTRY_VERIFY_PUBLISHED`      | `true`                   | download the published file and compare it byte for byte |
| `SPL_REGISTRY_GATE_TIMEOUT_SECONDS`  | `10`                     | how long a publication waits for the gate that serialises the quota count |
| `SPL_REGISTRY_UVLHUB_TIMEOUT`        | `60`                     | seconds per UVLHub call |
| `SPL_REGISTRY_UVLHUB_PUBLISH_TIMEOUT` | `600`                   | seconds the two calls that mint a DOI may wait on Zenodo |
| `SPL_REGISTRY_QUOTA_WINDOW_HOURS`    | `24`                     | the rolling window every quota is counted over |
| `SPL_REGISTRY_MAX_RELEASES_PER_USER` | `10`                     | per developer, per window |
| `SPL_REGISTRY_MAX_RELEASES_PER_SPL`  | `5`                      | per product line, per window |
| `SPL_REGISTRY_MAX_RELEASES_TOTAL`    | `100`                    | the ceiling that bounds the single key |
| `SPL_REGISTRY_MAX_SPLS_PER_USER`     | `5`                      | product lines one developer may own |

`UVLHUB_API_KEY` is deliberately never copied into `app.config`: that mapping
is dumped by `splent product:config`, by the settings screens and by Flask's
debug pages. It is read from the environment at call time in exactly one place,
`uvlhub.api_key()`, which is the only place in the whole workspace that reads
it server side.

Quotas are counted with SQL `COUNT`s, never in-process counters, because
several workers run in parallel and a per-process counter would multiply every
allowance by the number of them.

## 403 or 404

Every product line is in the public index unless an administrator withdraws it
with `visibility <spl> withdrawn`. That one flag decides what the publishing
endpoint says about a line that is not yours:

| the line is  | answer | why |
|--------------|--------|-----|
| listed       | `403`  | admitting the name is taken tells the caller nothing they cannot read in `GET /api/v1/spls` |
| withdrawn    | `404`  | the same answer, code and wording as a name nobody registered, so the write path cannot be walked to find what the read path hides |

Withdrawing hides a line. It deletes nothing: every release and every DOI stays
exactly where it is, and the owner can still publish to it.

## Authorship

A publication is credited to the publishing developer's profile, read server
side and never from a request field, because an author line a stranger can
choose is an impersonation vector on a permanent record.

The profile feature is **not** required. When the product installs it, the
credit is the `name` and `surname` on the developer's `UserProfile`, read
through `UserProfileService.get_by_user_id`. When it does not, or when the
developer never filled the form in, the credit is `SPLENT MARKETPLACE`. It is
never the email address, which would put a personal address on a permanent
public record.

A SPLENT profile holds a name and a surname and nothing else, so that is all
that is sent. There is no affiliation and no ORCID to send.

## Commands

```bash
splent db:seed
splent feature:spl_registry list
splent feature:spl_registry stuck [--hours 1]
splent feature:spl_registry reconcile [<spl>]
splent feature:spl_registry settle <spl> <version> [--doi ...] [--note ...]
splent feature:spl_registry set-owner <spl> <email>
splent feature:spl_registry visibility <spl> public|withdrawn
```

`splent db:seed` runs `SplRegistrySeeder`, which **carries the founding product
lines as data**. They were published before the registry existed, and their
name, description, mirror, DOI and file name are written out in `seeders.py`.
The seeder is what rebuilds the registry on a fresh database, and it is
idempotent.

It records no content digest for the lines it brings in. The digest is the
idempotency key, and a release carrying one is the registry promising these
exact bytes are what that DOI serves. Nothing has compared them, and one of the
three does not even serve a file named after the line
(`sample_splent_spl` serves `sample_splent_app.uvl`), so the digest is left
empty.

Seeded lines arrive with **no owner**, which is what stops any authenticated
developer from publishing to them; `set-owner` hands one over.

## Requires

`auth` (the User an owner and a publisher point at) and `apikeys` (the
`write_spl` Bearer token the publishing endpoint is guarded by).

`profile` is **optional**. It improves the credit on a publication and the name
shown on the public page, and the feature works without it.

## Tests

```bash
splent feature:test splent_feature_spl_registry
```

Unit, integration and functional. The suite never reaches UVLHub: the conftest
replaces the four relay calls **and** the HTTP client underneath them, and it
does so through its own `MonkeyPatch` rather than the shared fixture. That last
detail is not decoration. While the shared fixture was used, a single
`monkeypatch.undo()` inside a test restored the real relay along with the real
`UVLHUB_API_KEY`, and a test run minted a permanent DOI on production Zenodo.
Publishing is irreversible, so the guard has to be one a test cannot lift.
