- Python 88.7%
- HTML 10.8%
- Mako 0.5%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| docs | ||
| src | ||
| .gitignore | ||
| COPYING | ||
| COPYING.LESSER | ||
| MANIFEST.in | ||
| pyproject.toml | ||
| README.md | ||
splent_feature_dataset_transfer
The dataset_transfer feature of a SPLENT product line.
Offers of a dataset, and every version of it, to another account (DL-17 of uvlhub 3.0). The owner offers it, the account it is offered to accepts or declines it, and only then does the lineage change owner. It was part of splent_feature_dataset up to 0.13.0, reachable through API v1 alone; it is an optional feature of the OpenHubs line now (D10), with a page on the web and the rules below. A hub without it has no transfers at all.
A SPLENT feature is a Python package that a product composes with others.
Its models, routes, services, templates and hooks are registered when the
product starts. What this feature provides and requires is listed in the
[tool.splent.contract] section of pyproject.toml, which
splent feature:contract --write keeps in sync with the source.
Use it in a product
splent feature:add splent_feature_dataset_transfer
It requires auth (1.23.0 or later), dataset (0.14.0 or later) and mail
(1.5.0 or later). The change of the OpenHubs model that goes with it is
docs/openhubs_spl.uvl.patch: an optional
node under repositorio, with dataset_transfer => dataset, => auth and
=> mail.
API v1's transfer routes are served by splent_feature_dataset_api 0.4.0 or later in a product that has both (see "API v1" below).
The rules (DL-17)
- One answer, whether or not the account exists. An offer names its account by its address (the web, API v1) or by its id (API v1). When that is not an account that may sign in (none at that address, none with that id, or one switched off) the offer is kept all the same, with nobody behind it, and the sender is answered exactly as for an account: the same page, the same 202, the same listing, and the offer lapses as an unanswered one does. Nobody can accept it. So no answer says which addresses have an account or which accounts are switched off (A08-10), and while an offer waits its sender sees whom they named, never more: the address, or the id they gave. Once the account answers, the sender learns it.
- A mail with a signed link. An account that may sign in is mailed the
offer, with a link to its page (
/transfers/offers/<token>), signed with the product's key for tokens (the framework'ssplent_framework.keys, saltdataset-transfer-offer) and naming the offer and its recipient. The link opens nothing by itself: the page answers its recipient, signed in, and is a 404 for anyone else, a link that is not genuine, or one older than any offer lives. The mail carries a token, so mail sends it once, at once, keeps it with its link cut, and never sends it again; the answers to the sender carry no secret, and are retried. - Offers lapse.
DATASET_TRANSFER_EXPIRY_DAYS(14) after it was made an unanswered offer is cancelled as expired, the moment anything reads it: an answer, which is refused; a listing; a new offer of its lineage, which then goes through. Each new offer also settles a few others that lapsed, so there is no cron to run. - Locked answers. Accept, decline and cancel lock the offer (
SELECT ... FOR UPDATE) and read it again before they answer, and an acceptance locks the lineage too and records the answer in the transaction that moves it (dataset'sLineageService.change_owner, withcommit=False). An acceptance and a cancellation at the same time end one way, never both (A08-23, A10-09). - One live offer per lineage.
pending_keyislineage:<root id>while an offer is pending and empty after, under a unique key: a second offer of any version of the lineage is refused while the first waits, even when both are made at the same time. - A limit per account and day. An account makes
DATASET_TRANSFER_MAX_OFFERS_PER_DAY(10) offers in a day at most, whatever became of them and whether or not they reached an account, so the offers are nobody's way to mail strangers. Past it, the web says so and API v1 answers 429transfer_limit, withRetry-After.
What moves on acceptance, and what is refused before (a lineage split across accounts, one that changed owner after the offer), is dataset's: the whole lineage moves as a unit, with any file still in its old owner's folder.
On the web
- The offer, from the dataset's page: its owner sees "Offer to another
account" among its actions (dataset's
dataset.view.actionsslot), which opens/datasets/<id>/transfer, an address and an optional note. While an offer of the lineage waits, the page says to whom it went, and offers to withdraw it. - The inbox,
/transfers: Transfers in the Account section of the menu and of the user menu, after Edit profile, with the count of the offers that wait for the account's answer. What waits for its answer, with Accept and Decline; what it offered, with Withdraw; and what became of the rest. - The page of an offer, which the mail links to, with Accept and
Decline. It carries its token in the address, so it is sent with auth's
keep_token_private: no Referer, no cache, no script of another site.
Every page reads in the request's language (es included), and so do the
refusals; API v1 answers them in English, as it always did.
API v1
The five routes uvlhub 2.12's clients call are dataset_api's, which asks
this feature's TransferService (registered under that name, the one
dataset gave it):
| Route | Methods |
|---|---|
/api/v1/datasets/<id>/transfer |
POST |
/api/v1/datasets/transfers |
GET |
/api/v1/datasets/transfers/<id>/accept |
POST |
/api/v1/datasets/transfers/<id>/decline |
POST |
/api/v1/datasets/transfers/<id>/cancel |
POST |
They keep their methods, statuses and keys (CO-1). What changed is what
DL-17 asks: an offer to an address or an id with no account that may sign
in is a 202 like any other, where 2.12 answered 404 or 400, and the
to_user_id of an offer to an address is null for its sender until the
account answers. A product without this feature serves none of them, and
dataset_api registers no datasets:transfer scope.
Configuration
| Setting | Default | Means |
|---|---|---|
DATASET_TRANSFER_EXPIRY_DAYS |
14 | Days an offer waits for its answer (1 to 365) |
DATASET_TRANSFER_MAX_OFFERS_PER_DAY |
10 | Offers an account makes in a day (0 for no limit) |
Both are derivation parameters ([tool.splent.config_schema]): the
product decides them.
The table
dataset_transfer_request, the one dataset kept, with its rows and its ids,
which uvlhub 2.12's mails and API answers carry.
dataset_transfer0001_requeststakes it over as uvl took featuremodel's table over: a database dataset migrated has it already, and the revision leaves it alone, so nothing is created twice and no row moves; a new database gets it here, as dataset's7e2d3e88f41cmade it. Its downgrade drops it only when it holds no offer. dataset 0.14.0'sdataset0011_transfers_moveddrops the table dataset made when it is empty and not taken over yet, so a hub without this feature keeps no table of it.dataset_transfer0002_offer_rulesaddsto_addressandto_named_id(the account as its sender named it),expires_at,cancel_reason(sender,expired,migrationorduplicate) andpending_key(unique), and letsto_user_idbe NULL. A pending offer gets the default window from the day of the migration; two pending offers of one lineage, which only check-then-act could make, keep the oldest, and the others are cancelled asduplicate. The downgrade lets go of the offers that reached no account, which the older table cannot hold.
An account that goes takes the offers it made or received with it, in the
transaction of its deletion (auth's user-deleting).
Moving from uvlhub 2.12 (D13 b)
The migrator loads dataset_transfer_request with its ids. An offer still
pending at the cutover is cancelled: status CANCELLED, resolved_at the
cutover, cancel_reason migration, no pending_key; the others keep
their state. to_address, to_named_id and expires_at stay NULL for
every row: an offer of 2.12 names its recipient by its account, as it did.
The notices to both parties are the migrator's, held in mail's outbox until
the end of RB-2.
Develop
splent feature:test splent_feature_dataset_transfer
splent feature:contract splent_feature_dataset_transfer
A product that does not declare it tests it in a neutral app, with the
releases of what it requires; --with splent_feature_dataset loads
dataset's working copy instead, until dataset 0.14.0 is released.
Release
splent feature:release splent_feature_dataset_transfer --dry-run --bump minor
splent feature:release splent_feature_dataset_transfer
The first command rehearses the release and changes nothing. The second publishes it to the git forge and to PyPI, and a PyPI version is permanent.